# Trace: Identify and Fix Rust Engine Gaps vs Java
Agent: claude-code | Model: Claude Opus 4.6 | Project: mage
---
## User
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.
## User
/clear
clear
## User
## User
Compare our rust engine with the Java game engine. Identify gaps that would prevent us from correctly running our cards in the 4 sets we have, and update @mtg-rl/ROADMAP.md with the deficiencies.
## Assistant
## Assistant
I'll start by thoroughly exploring both engines in parallel to identify gaps.
## Assistant
### Tool: Task
**Args:**
```json
{
"description": "Explore Rust engine capabilities",
"prompt": "Thoroughly explore the Rust mtg-rl engine at /mnt/dest-btrfs/home/jc/src/mage/mtg-rl/ to catalog all implemented game mechanics and engine capabilities. I need a comprehensive inventory of:\n\n1. **Effect variants** - Read mtg-engine/src/abilities.rs to find all Effect enum variants and which ones have implementations vs are no-ops\n2. **StaticEffect variants** - All StaticEffect enum variants and whether they're enforced\n3. **Cost variants** - All Cost enum variants and which are implemented in pay_costs()\n4. **EventType variants** - All event types and triggers\n5. **Game loop features** - Read mtg-engine/src/game.rs to understand what the game loop handles (combat, state-based actions, priority, stack, targeting, etc.)\n6. **Zone management** - How zones work (library, hand, battlefield, graveyard, exile, stack)\n7. **Mana system** - How mana/costs work\n8. **Combat system** - How combat phases work\n9. **Targeting system** - How targeting/TargetSpec works\n10. **Token system** - How tokens are created\n11. **Counter system** - How counters work\n12. **Keyword abilities** - Which keywords are mechanically enforced vs just flags\n13. **Player decision making** - The PlayerDecisionMaker trait and what decisions it supports\n14. **Replacement effects** - Whether they exist/work\n15. **Continuous effects / layers** - Whether there's a layer system\n\nRead the key files: abilities.rs, game.rs, effects.rs (if exists), constants.rs, mana.rs, and any other relevant engine files. For game.rs especially, look at execute_effects() to see which Effect variants have real match arms vs fall through to `_ => {}`.\n\nProvide a detailed inventory with specifics about what IS and ISN'T implemented.",
"run_in_background": true,
"subagent_type": "Explore"
}
```
## Assistant
**Result** (success):
```
Async agent launched successfully.
agentId: ac21389 (internal ID - do not mention to user. Use to resume later if needed.)
The agent is working in the background. You will be notified automatically when it completes.
Continue with other tasks.
output_file: /tmp/claude-1000/-mnt-dest-btrfs-home-jc-src-mage/tasks/ac21389.output
To check progress before completion (optional), use Read or Bash tail on the output file.
```
## Assistant
### Tool: Task
**Args:**
```json
{
"description": "Explore Java engine capabilities",
"prompt": "Explore the Java XMage engine at /mnt/dest-btrfs/home/jc/src/mage/ to catalog the game engine's key capabilities. I need to understand what the full-featured Java engine provides so we can identify gaps in the Rust reimplementation. Focus on:\n\n1. **Game loop** - Read Mage/src/main/java/mage/game/GameImpl.java (or similar) to understand the main game loop, priority system, and turn structure\n2. **Effect system** - Look at Mage/src/main/java/mage/abilities/effects/ to understand the effect hierarchy and key effect types (OneShotEffect, ContinuousEffect, ReplacementEffect)\n3. **Continuous effects / layers** - Look for the layer system (7 layers: Copy, Control, Text, Type, Color, Ability, P/T). Check Mage/src/main/java/mage/game/permanent/PermanentImpl.java or similar\n4. **Combat system** - How combat works, including first/double strike, trample, etc.\n5. **Stack/priority** - How the stack resolves, how priority passes\n6. **Targeting** - How targets are chosen and validated\n7. **State-based actions** - What SBAs are checked\n8. **Equipment/Aura attachment** - How attachment works\n9. **Planeswalker system** - Loyalty abilities\n10. **Replacement effects** - How replacement effects intercept events\n11. **X-cost spells** - How X is determined and used\n12. **Modal spells** - How mode selection works\n13. **Copy effects** - How spell/permanent copying works\n14. **Triggered abilities** - How triggers fire and go on the stack\n15. **Keyword enforcement** - Which keywords are mechanically enforced (flying blocks flying, deathtouch kills, lifelink gains life, etc.)\n\nFocus on the Mage/ core module. Look at key files in:\n- Mage/src/main/java/mage/game/\n- Mage/src/main/java/mage/abilities/\n- Mage/src/main/java/mage/abilities/effects/\n- Mage/src/main/java/mage/game/combat/\n- Mage/src/main/java/mage/game/permanent/\n- Mage/src/main/java/mage/game/stack/\n\nProvide a structured summary of what the Java engine implements that would be relevant for comparison.",
"run_in_background": true,
"subagent_type": "Explore"
}
```
## Assistant
**Result** (success):
```
Async agent launched successfully.
agentId: a2b068c (internal ID - do not mention to user. Use to resume later if needed.)
The agent is working in the background. You will be notified automatically when it completes.
Continue with other tasks.
output_file: /tmp/claude-1000/-mnt-dest-btrfs-home-jc-src-mage/tasks/a2b068c.output
To check progress before completion (optional), use Read or Bash tail on the output file.
```
## Assistant
Both agents are still exploring. Let me also look at what cards in our 4 sets use Custom effects (the main gap indicator) to understand the scope of unimplemented features.
## Assistant
### Tool: Task
**Args:**
```json
{
"description": "Catalog Custom effects in card sets",
"prompt": "Search through the Rust card implementations in /mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-cards/src/sets/ to catalog all uses of Effect::Custom, StaticEffect::Custom, and Cost::Custom across the 4 sets (fdn.rs, tla.rs, tdm.rs, ecl.rs).\n\nFor each set file:\n1. Count total Effect::Custom usages\n2. Count total StaticEffect::Custom usages \n3. Count total Cost::Custom usages\n4. Group the Custom strings by category/pattern to identify what engine features are missing. For example:\n - \"Exile target creature\" patterns\n - \"Return target creature to hand\" patterns\n - Equipment/Aura related\n - Planeswalker related\n - X-cost related\n - \"Enters tapped\" patterns\n - Counter-manipulation patterns\n - Token-creation patterns\n - Life gain/loss patterns\n - Card draw patterns\n - Discard patterns\n - \"Can't be blocked\" patterns\n - Protection patterns\n - Damage prevention patterns\n - Copying patterns\n - etc.\n\n5. Also look for any TargetSpec usage patterns and what decision types are used.\n\nThe goal is to understand WHAT specific mechanics/effects are still using Custom fallbacks and how many cards each missing feature affects. Group them meaningfully so we can prioritize engine work.\n\nProvide counts per category per set, and identify the top 20 most common Custom effect patterns.",
"run_in_background": true,
"subagent_type": "Explore"
}
```
## Assistant
**Result** (success):
```
Async agent launched successfully.
agentId: a715424 (internal ID - do not mention to user. Use to resume later if needed.)
The agent is working in the background. You will be notified automatically when it completes.
Continue with other tasks.
output_file: /tmp/claude-1000/-mnt-dest-btrfs-home-jc-src-mage/tasks/a715424.output
To check progress before completion (optional), use Read or Bash tail on the output file.
```
## Assistant
All three research agents are still working. Let me also check what keyword abilities are defined vs mechanically enforced in the Rust engine, since that's a key area where gaps might exist.
## Assistant
### Tool: Task
**Args:**
```json
{
"description": "Check keyword enforcement in Rust",
"prompt": "In the Rust mtg-rl engine at /mnt/dest-btrfs/home/jc/src/mage/mtg-rl/:\n\n1. Read mtg-engine/src/constants.rs to find all KeywordAbilities flags defined\n2. Search mtg-engine/src/game.rs for each keyword name to see which ones are actually mechanically enforced. For example:\n - FLYING: Is there code that checks flying during declare blockers?\n - FIRST_STRIKE/DOUBLE_STRIKE: Is there first-strike damage step handling?\n - TRAMPLE: Is excess damage assigned to defending player?\n - DEATHTOUCH: Does any damage from deathtouch creature destroy?\n - LIFELINK: Does damage from lifelink creature gain life?\n - VIGILANCE: Does attacking with vigilance skip tapping?\n - REACH: Can reach creatures block flyers?\n - MENACE: Must be blocked by 2+?\n - HASTE: Can attack/tap without summoning sickness?\n - HEXPROOF: Can't be targeted by opponents?\n - INDESTRUCTIBLE: Doesn't die to destroy effects?\n - FLASH: Can be cast at instant speed?\n - DEFENDER: Can't attack?\n - WARD: Counter unless cost is paid?\n - PROTECTION: Prevention, blocking, targeting, enchanting?\n\n3. Also check if there's any state-based action checking (e.g., creatures with 0 toughness die, legends rule, planeswalker uniqueness)\n\nReport which keywords are enforced vs just decorative flags, and which state-based actions exist.",
"run_in_background": true,
"subagent_type": "Explore"
}
```
## Assistant
**Result** (success):
```
Async agent launched successfully.
agentId: aa5f9b3 (internal ID - do not mention to user. Use to resume later if needed.)
The agent is working in the background. You will be notified automatically when it completes.
Continue with other tasks.
output_file: /tmp/claude-1000/-mnt-dest-btrfs-home-jc-src-mage/tasks/aa5f9b3.output
To check progress before completion (optional), use Read or Bash tail on the output file.
```
## Assistant
All four agents are still working. I'll wait for them to complete before synthesizing findings.
## User
aa5f9b3
completed
Agent "Check keyword enforcement in Rust" completed
Perfect! Now I have all the information I need. Let me create a comprehensive report.
## Summary: Keyword Abilities & State-Based Actions in mtg-rl Engine
Based on my analysis of the Rust mtg-rl engine at `/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/`, here's the status of keyword ability enforcement and state-based actions:
### Keyword Abilities Status
**47 keywords defined in `/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/constants.rs` (lines 533-584):**
```
FLYING, FIRST_STRIKE, DOUBLE_STRIKE, TRAMPLE, HASTE, VIGILANCE, LIFELINK, DEATHTOUCH,
REACH, DEFENDER, MENACE, FLASH, INDESTRUCTIBLE, HEXPROOF, SHROUD, FEAR, INTIMIDATE,
PROTECTION, WARD, PROWESS, UNDYING, PERSIST, WITHER, INFECT, SHADOW, UNBLOCKABLE,
CHANGELING, CASCADE, CONVOKE, DELVE, EVOLVE, EXALTED, EXPLOIT, FLANKING, FORESTWALK,
ISLANDWALK, MOUNTAINWALK, PLAINSWALK, SWAMPWALK, TOTEM_ARMOR, TOXIC, AFFLICT, BATTLE_CRY,
SKULK, FABRICATE, STORM, PARTNER
```
#### Mechanically Enforced Keywords
1. **HASTE** - Enforced
- Used in `can_attack()` (permanent.rs:250) to bypass summoning sickness
- Granted during `GainControlUntilEndOfTurn` effect (game.rs:1727)
2. **FLYING** - Enforced
- Used in `can_block()` check (combat.rs:205): flyers can only be blocked by flying or reach creatures
3. **REACH** - Enforced
- Used in `can_block()` check (combat.rs:205): reach creatures can block flyers
4. **DEFENDER** - Enforced
- Used in `can_attack()` check (permanent.rs:249): creatures with defender cannot attack
5. **FIRST_STRIKE & DOUBLE_STRIKE** - Enforced
- Checked during combat damage assignment (combat.rs:241-248)
- Controls whether damage is dealt in first strike step vs regular combat damage step
- `has_first_strikers()` determines if FirstStrikeDamage step is needed (combat.rs:166-186)
6. **TRAMPLE** - Enforced
- Excess damage from trampler assigned to defending player when blockers are destroyed (combat.rs:296-298)
7. **DEATHTOUCH** - Enforced
- Only 1 damage needed to be lethal for blocking creatures (combat.rs:280-286)
- Minimizes damage assignment to blockers (combat.rs:281-282)
8. **MENACE** - Enforced
- Checked via `satisfies_menace()` function (combat.rs:216-224)
- Requires 2+ blockers if blocked at all
9. **INDESTRUCTIBLE** - Enforced
- Checked in state-based action for lethal damage (state.rs:296)
- Creatures with indestructible survive lethal damage
#### Keywords with Partial/Limited Support
10. **VIGILANCE** - NOT Enforced
- No code path prevents tapping when attacking
- Combat phase is not implemented in the game loop
11. **LIFELINK** - NOT Enforced
- No code connects lifelink to damage → life gain
- Damage is applied directly to creatures/players with no lifelink check
12. **FLASH** - Partially Enforced
- Used to block casting during main phases (game.rs:572)
- But since combat is not implemented, ability is vestigial
#### Keywords as Decorative Flags (Not Enforced)
The following keywords are defined but have **zero mechanical enforcement**:
- **HEXPROOF** - Defined but never checked in blocking/targeting logic
- **SHROUD** - Defined but never checked
- **FEAR** - Defined but not checked in blocker restrictions
- **INTIMIDATE** - Defined but not checked in blocker restrictions
- **PROTECTION** - Defined but not checked for prevention/targeting/blocking
- **WARD** - Defined but not checked
- **PROWESS** - Defined but never triggers on spells cast
- **UNDYING** - Defined but doesn't trigger on death
- **PERSIST** - Defined but doesn't trigger on death
- **WITHER** - Defined but doesn't mark damage differently
- **INFECT** - Defined but no poison counter interaction
- **SHADOW** - Defined but not checked in blocker restrictions
- **UNBLOCKABLE** - Defined but not checked; combat not implemented
- **CHANGELING** - Defined but no creature type checking
- **CASCADE** - Defined but no spell cascade triggering
- **CONVOKE** - Defined but no mana ability interaction
- **DELVE** - Defined but not used in cost payment
- **EVOLVE** - Defined but no +1/+1 counter triggering
- **EXALTED** - Defined but no attack damage boost
- **EXPLOIT** - Defined but no creature sacrifice checking
- **FLANKING** - Defined but not checked in blocker restrictions
- **FORESTWALK, ISLANDWALK, MOUNTAINWALK, PLAINSWALK, SWAMPWALK** - Defined but not checked in blocker restrictions
- **TOTEM_ARMOR** - Defined but doesn't prevent permanent destruction
- **TOXIC** - Defined but no poison counter assignment
- **AFFLICT** - Defined but no damage/life trade logic
- **BATTLE_CRY** - Defined but no attack damage boost
- **SKULK** - Defined but not checked in blocker restrictions
- **FABRICATE** - Defined but no token generation
- **STORM** - Defined but no copy-on-cast triggering
- **PARTNER** - Defined but no commander-zone sharing
### State-Based Actions (Checked in `state.rs:check_state_based_actions()`)
**Implemented state-based actions:**
1. **Rule 704.5a** - Player at 0 or less life loses (state.rs:280-282)
2. **Rule 704.5c** - Player with 10+ poison counters loses (state.rs:285-287)
3. **Rule 704.5f** - Creature with 0 or less toughness goes to graveyard (state.rs:294-295)
4. **Rule 704.5g** - Creature with lethal damage marked on it is destroyed (if not indestructible) (state.rs:296-297)
5. **Rule 704.5j** - Planeswalker with 0 or less loyalty goes to graveyard (state.rs:305-308)
6. **Rule 704.5k** - Legend rule - legendary permanents with same name (state.rs:312-338)
7. **Rule 704.5r** - +1/+1 and -1/-1 counter annihilation (state.rs:341-347)
### Critical Limitation: Combat Phase Not Implemented
The game loop in `game.rs` only handles these steps:
- **PhaseStep::Untap** - Untaps permanents, clears summoning sickness
- **PhaseStep::Draw** - Active player draws a card
- **PhaseStep::Cleanup** - Cleanup phase (hand size, damage reset, EOT effects)
**Missing combat steps entirely:**
- BeginCombat
- DeclareAttackers
- DeclareBlockers
- FirstStrikeDamage
- CombatDamage
- EndCombat
This means although the combat module (`combat.rs`) has fully implemented functions for combat damage assignment, blocker restrictions, and first/double strike timing, they are **never called** by the game engine. Combat effectively does not happen.
### Summary Table
| Keyword | Status | Enforcement |
|---------|--------|-------------|
| FLYING | Enforced | Blocks blocker legality check |
| REACH | Enforced | Blocks blocker legality check |
| DEFENDER | Enforced | Prevents attacking |
| HASTE | Enforced | Bypasses summoning sickness |
| FIRST_STRIKE | Enforced | Controls damage step timing |
| DOUBLE_STRIKE | Enforced | Allows damage both steps |
| TRAMPLE | Enforced | Excess damage to player |
| DEATHTOUCH | Enforced | Only 1 damage is lethal |
| MENACE | Enforced | Requires 2+ blockers |
| INDESTRUCTIBLE | Enforced | Survives lethal damage |
| VIGILANCE | Not Enforced | No tap prevention on attack |
| LIFELINK | Not Enforced | No damage→life connection |
| All Others (37+) | Decorative | Zero mechanical implementation |
### Files Involved
- `/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/constants.rs` - Keyword definitions (lines 533-622)
- `/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/permanent.rs` - Keyword checking methods (lines 127-192)
- `/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/combat.rs` - Combat damage and blocking logic (lines 199-224, 233-302)
- `/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/state.rs` - State-based action checks (lines 271-349)
- `/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/game.rs` - Game loop & turn-based actions (lines 363-447, 771-820)
total_tokens: 72014
tool_uses: 24
duration_ms: 63618
Full transcript available at: /tmp/claude-1000/-mnt-dest-btrfs-home-jc-src-mage/tasks/aa5f9b3.output
## Assistant
Good, the keyword enforcement analysis is complete. Key finding: combat phase steps are **not in the game loop** even though combat.rs has the logic. That's a major gap. Waiting for the other three agents to finish.
## User
ac21389
completed
Agent "Explore Rust engine capabilities" completed
Perfect! Now I have comprehensive information. Let me create the final report:
## Comprehensive MTG-RL Engine Inventory
I've completed a thorough exploration of the Rust mtg-rl engine at `/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/`. Here's a detailed catalog of all implemented game mechanics and engine capabilities:
---
### OVERVIEW
- **Total Engine Code**: ~14,628 lines of Rust across 21 source files
- **Architecture**: 5 crates (mtg-engine, mtg-cards, mtg-ai, mtg-python, mtg-tests)
- **Card Coverage**: 1,333 cards implemented across 4 sets (FDN, TLA, TDM, ECL)
- **Performance**: ~88 games/sec single-threaded, ~585/sec with parallelism
- **Design**: Data-oriented (enums + match rather than inheritance)
---
### 1. EFFECT SYSTEM (abilities.rs)
**62 Effect Enum Variants - Status:**
#### FULLY IMPLEMENTED (with real match arms in execute_effects):
- **Damage**: DealDamage, DealDamageAll, DealDamageOpponents, DealDamageVivid
- **Life**: GainLife, GainLifeVivid, LoseLife, LoseLifeOpponents, LoseLifeOpponentsVivid, SetLife
- **Destruction**: Destroy, DestroyAll, Exile, Sacrifice, PutOnLibrary
- **Card Movement**: Bounce, ReturnFromGraveyard, Reanimate, DrawCards, DrawCardsVivid, DiscardCards, DiscardOpponents, Mill, SearchLibrary, LookTopAndPick
- **Counters**: AddCounters, AddCountersSelf, AddCountersAll, RemoveCounters
- **Tokens**: CreateToken, CreateTokenTappedAttacking, CreateTokenVivid
- **Mana**: AddMana
- **Combat**: CantBlock, Fight, Bite, MustBlock
- **Stats**: BoostUntilEndOfTurn, BoostPermanent, BoostAllUntilEndOfTurn, BoostUntilEotVivid, BoostAllUntilEotVivid, SetPowerToughness
- **Keywords**: GainKeywordUntilEndOfTurn, GainKeyword, LoseKeyword, GrantKeywordAllUntilEndOfTurn, Indestructible, Hexproof
- **Control**: GainControl, GainControlUntilEndOfTurn
- **Tap**: TapTarget, UntapTarget
- **Stack**: CounterSpell
- **Modal**: Modal (full branching and choice)
- **Conditional**: DoIfCostPaid, ChooseCreatureType, ChooseTypeAndDrawPerPermanent
- **Scry**: Scry
#### NO IMPLEMENTATION (catch-all `_ => {}`):
- GainProtection (parsing code exists, but no effect)
- PreventCombatDamage (not handled)
- Custom(String) (fallback for unimplemented effects)
#### NOTES ON IMPLEMENTATIONS:
- **BoostUntilEndOfTurn**: Uses direct counter modification instead of proper continuous effects (simplified but functional)
- **Scry**: AI asked to choose which cards to put on bottom
- **Fight/Bite**: Proper target resolution with fallback to strongest creatures
- **Vivid effects**: Count actual colors among permanents you control (ECL mechanic)
- **Modal**: Recursive execute_effects for chosen modes
---
### 2. STATIC EFFECTS (abilities.rs)
**13 StaticEffect Enum Variants - Status:**
#### FULLY DEFINED (for card data):
- **Boost**: Lord effects with filter + power/toughness (e.g., "Other creatures you control get +1/+1")
- **GrantKeyword**: Grant keywords to filtered permanents (e.g., "Creatures you control have flying")
- **RemoveKeyword**: Remove keywords from filtered permanents
- **CantAttack**: Filtered permanents can't attack
- **CantBlock**: Filtered permanents can't block
- **CostReduction**: Reduce casting cost of filtered spells
- **EntersTapped**: Permanents matching filter enter tapped
- **EntersTappedUnless**: Conditional "enters tapped" (e.g., dual lands)
- **Ward**: "When targeted by opponent's spell/ability, counter it unless they pay [cost]"
- **Evoke**: Alternative casting cost with ETB sacrifice
- **CantGainLife**: Other players can't gain life
- **CantDrawExtraCards**: Other players can't draw extra cards
- **Custom(String)**: Catch-all for complex effects
#### ENFORCEMENT STATUS:
- Most are **declared but not enforced** in the game loop (they serve as data in card definitions)
- **Boost** and **GrantKeyword**: Applied via continuous effect system and layer calculations
- **CantAttack/CantBlock**: Used by combat validation (can_attack/can_block checks)
- **EntersTapped**: Checked during permanent creation
- **Evoke**: Declared but not mechanically enforced (would require alternative cost handling)
- **Ward**: Declared but no targeting-cost-paying logic implemented
---
### 3. COST SYSTEM (abilities.rs)
**12 Cost Enum Variants - All Declared:**
#### FULLY IMPLEMENTED in pay_costs():
- **Mana(Mana)**: Parsed from strings like "{2}{B}"; validated against mana pool
- **TapSelf**: Taps the source permanent
- **UntapSelf**: Untaps the source permanent
- **PayLife(u32)**: Deducts life from controller
- **SacrificeSelf**: Sacrifices the source permanent
- **Discard(u32)**: Asks player which cards to discard
- **ExileFromHand(u32)**: Exiles cards from hand (simplified)
- **ExileFromGraveyard(u32)**: Exiles cards from graveyard
- **RemoveCounters(type, count)**: Removes counters from source
#### PARTIALLY IMPLEMENTED:
- **SacrificeOther(String)**: Filter text stored but only sacrifices first match (no choice)
- **Blight(u32)**: ECL mechanic; implemented as equivalent to RemoveCounters("-1/-1", count)
- **RevealFromHand(String)**: Declared but no reveal validation logic
- **Custom(String)**: Fallback for complex costs (description only)
---
### 4. EVENT SYSTEM (events.rs)
**~90 EventType Enum Variants Declared:**
#### CATEGORIZED BY TYPE:
- **Turn Structure** (13 events): BeginTurn, EndTurn, ChangePhase, ChangeStep, UntapStep, UpkeepStep, DrawStep, PrecombatMain, BeginCombat, DeclareAttackers, DeclareBlockers, CombatDamageStep, EndStep, CleanupStep, AtEndOfTurn
- **Zone Changes** (6 events): ZoneChange, ZoneChanged, DrawCard, DrewCard, DiscardCard, DiscardedCard, EntersTheBattlefield, EnteredTheBattlefield, Dies, ExileCard, ExiledCard, MillCards, MilledCard
- **Spells/Abilities** (6 events): CastSpell, SpellCast, ActivateAbility, ActivatedAbility, TriggeredAbility, ResolveSpell, SpellResolved, Counter, Countered
- **Mana** (4 events): AddMana, ManaAdded, ManaPaid, EmptyManaPool
- **Damage** (6 events): DamagePlayer, DamagedPlayer, DamagePermanent, DamagedPermanent, CombatDamageApplied, PreventDamage, PreventedDamage
- **Life** (7 events): GainLife, GainedLife, LoseLife, LostLife, PlayerLifeChange, PayLife, LifePaid
- **Combat** (6 events): DeclareAttacker, AttackerDeclared, DeclaredAttackers, DeclareBlocker, BlockerDeclared, DeclaredBlockers, CreatureBlocked, UnblockedAttacker
- **Permanents** (7 events): Tap, Tapped, Untap, Untapped, DestroyPermanent, DestroyedPermanent, SacrificePermanent, SacrificedPermanent, Regenerate, Regenerated
- **Counters** (4 events): AddCounters, CountersAdded, RemoveCounters, CountersRemoved
- **Tokens** (2 events): CreateToken, CreatedToken
- **Lands** (2 events): PlayLand, LandPlayed
- **Players** (6 events): Loses, Lost, Wins, SearchLibrary, LibrarySearched, ShuffleLibrary, LibraryShuffled
- **Control** (3 events): GainControl, GainedControl, LostControl
- **Targeting** (2 events): Target, Targeted
- **Misc** (5 events): Attach, Attached, Unattach, Unattached, Mulligan, Scry, Scried, BecomeMonarch, Transforming, Transformed
#### USAGE IN TRIGGERED ABILITIES:
The **AbilityStore** tracks which triggered abilities respond to which EventTypes. Pre/post-event pairs (e.g., EntersTheBattlefield → EnteredTheBattlefield) allow replacement effects to intercept or modify events.
---
### 5. GAME LOOP (game.rs)
**The main game runner implements the MTG turn sequence:**
#### TURN STRUCTURE (PhaseStep enum from constants.rs):
1. **Untap** — Untap permanents, clear mana pools
2. **Upkeep** — Beginning-of-upkeep triggers
3. **Draw** — Active player draws a card
4. **PrecombatMain** — First main phase (land play, spells, abilities)
5. **BeginCombat** → **DeclareAttackers** → **DeclareBlockers** → **FirstStrikeDamage** → **CombatDamage** → **EndCombat** (combat phase)
6. **PostcombatMain** — Second main phase
7. **EndStep** → **Cleanup** — End of turn cleanup
#### GAME LOOP FLOW (process_step):
1. **Turn-based actions**: Untap, draw, cleanup (automatic)
2. **State-based actions**: Creatures with 0 toughness die; players with ≤0 life lose; loop until none found
3. **Triggered abilities**: Queued on stack (TODO: not yet fully implemented)
4. **Priority loop**: Players gain priority, can cast spells/activate abilities, pass until all pass or stack resolves
5. **Stack resolution**: Top item resolves → state-based actions → triggers → repeat
#### FEATURES:
- **London mulligan** support (draw 7, optionally mulligan repeatedly; each mulligan puts bottom N)
- **Priority system** with PriorityTracker (active player regains priority after action)
- **Mana pool** cleared at phase boundaries
- **End-of-turn effects** cleaned up (granted keywords, temporary control changes reverted, damage cleared)
- **Summoning sickness** tracked and enforced (creatures can't attack or use {T} on turn they entered)
#### LIMITATIONS:
- Triggered abilities partially implemented (TODO in comments)
- No replacement effects enforcement (declared in effects.rs but not integrated into game loop)
- Combat damage assignment simplified (first blocker takes all damage, overflow goes to player)
---
### 6. ZONE MANAGEMENT (zones.rs, constants.rs)
**8 Zones Implemented:**
1. **Library** — Ordered deck (top = index 0); peek/draw/shuffle; put_on_top/bottom
2. **Hand** — Unordered cards; 7-card max size (enforced in cleanup)
3. **Battlefield** — Contains Permanent structs, not just IDs; indexed by ObjectId
4. **Graveyard** — Unordered cards; public info zone
5. **Exile** — Unordered cards; public info zone
6. **Stack** — StackItem entries (spells with controller); LIFO resolution
7. **Command** — For commanders/conspiracies (declared but not fully used)
8. **Outside** — Cards outside the game
#### ZONE INFRASTRUCTURE:
- **ZoneLocation** struct tracks zone + controller for each card
- **Card store** (CardData) separate from zone containers
- **Permanents** on battlefield have additional state (tapped, damage, counters, attachments, etc.)
- **Zone change counter** tracks how many times object changed zones (for state-based actions)
---
### 7. MANA SYSTEM (mana.rs, mana_pool.rs)
**Mana Struct:**
- **Colored**: white, blue, black, red, green (u32 each)
- **Colorless**: colorless (e.g., from Wastes)
- **Generic**: can be paid by any color
- **Any**: mana that can be any color (from "add one mana of any color")
#### FEATURES:
- **Mana cost parsing** from strings: "{2}{B}" → Mana { generic: 2, black: 1, ... }
- **Mana payment validation** via can_pay() — checks if pool has required colors + enough generic to fill gaps
- **Simplified hybrid handling** — does not track hybrid mana ({B/R}, {2/G}); treats as generic
- **Mana pool operations**: add(), clear() at phase boundaries
- **Mana color extraction** — colors() returns Vec present in the pool
#### LIMITATIONS:
- Hybrid mana not supported (would require additional complexity)
- Snow mana not tracked separately
- No "spend only" mana restrictions
- No "restricted mana" types (e.g., mana that can't be used for creatures)
---
### 8. COMBAT SYSTEM (combat.rs, game.rs)
**Full Combat Implementation:**
#### CombatState Struct:
- **attackers**: Vec of attacking creature IDs
- **groups**: Vec (one per attacker + its blockers)
- **blocker_to_attacker**: HashMap for quick lookup
- **first_strike_dealt**: Flag for damage step ordering
#### CombatGroup:
- attacker_id + defending_id (player or planeswalker)
- blockers: Vec (order matters for damage assignment)
- damage_to_blockers: HashMap (resolved damage amounts)
- trample_damage: Overflow from unblocked/lethal-to-blockers damage
#### VALIDATED:
- **can_attack()**: Checks permanent isn't tapped, doesn't have summoning sickness, isn't a land
- **can_block()**: Checks permanent isn't tapped, has flying/reach or blocker is flying, respects blocking restrictions
- **First strike**: Detects first/double strike keywords; requires separate damage step
- **Evasion**: Unblockable creatures, flying (can block flying), reach (can block flying)
- **Trample**: Overflow damage to blocking player
#### SIMPLIFIED:
- Damage assignment is **automatic**: first blocker takes attacker's full power, overflow to next blocker
- No **trample damage assignment** to defending player (just counts overflow)
- **No combat tricks during declare**: Can't respond between declare attackers and blockers
- **No changing blockers after declared**
---
### 9. TARGETING SYSTEM (abilities.rs, targets.rs, decision.rs)
**TargetSpec Enum (from abilities.rs):**
- None, Creature, CreatureOrPlayer, Player, Permanent, PermanentFiltered(String), Spell, CardInGraveyard, CardInYourGraveyard, CreatureYouControl, OpponentCreature, Pair{first, second}, Multiple{spec, count}, Custom(String)
**TargetDefinition (from targets.rs):**
- Stores zone, filter, min/max targets, is_targeted flag, outcome (for AI)
- Supports "up to N targets" and "N targets total"
**SelectedTargets:**
- Vec — stores ID, is_player flag, player_id, amount (for divided damage), legality
**Game Loop Targeting:**
- Asks PlayerDecisionMaker::choose_targets() for legal targets
- Validates count and legality
- Tracks targets through resolution
- Handles "no legal targets" gracefully (effect fizzles)
#### FEATURES:
- Filters are **string-based** ("creatures you control", "nonland permanents", etc.)
- No formal filter DSL; matching done with string contains() checks
- Targets are **validated at resolution** (hexproof, shroud, protection checks skipped)
- Pair targets support fight/bite mechanics (your creature + opponent's creature)
---
### 10. KEYWORD ABILITIES (constants.rs)
**KeywordAbilities Bitflags (u64):**
- 47 keyword flags defined: FLYING, FIRST_STRIKE, DOUBLE_STRIKE, TRAMPLE, HASTE, VIGILANCE, LIFELINK, DEATHTOUCH, REACH, DEFENDER, MENACE, FLASH, INDESTRUCTIBLE, HEXPROOF, SHROUD, FEAR, INTIMIDATE, PROTECTION, WARD, PROWESS, UNDYING, PERSIST, WITHER, INFECT, SHADOW, UNBLOCKABLE, CHANGELING, CASCADE, CONVOKE, DELVE, EVOLVE, EXALTED, EXPLOIT, FLANKING, FORESTWALK, ISLANDWALK, MOUNTAINWALK, PLAINSWALK, SWAMPWALK, TOTEM_ARMOR, TOXIC, AFFLICT, BATTLE_CRY, SKULK, FABRICATE, STORM, PARTNER
#### ENFORCEMENT:
- **Mechanically enforced**: FLYING (combat), HASTE (summoning sickness), DEFENDER (can't attack), REACH (can block flying)
- **Declared but not enforced**: STORM, CASCADE, DELVE, CONVOKE, SHADOW, UNBLOCKABLE (requires custom logic)
- **End-of-turn keywords**: WARD, PROTECTION, granted/removed via granted_keywords/removed_keywords fields
#### CHECKING:
- Keyword parsing via keyword_from_name("flying") → Option
- Permanent.keywords() returns effective keywords = (base | granted) & !removed
---
### 11. CONTINUOUS EFFECTS & LAYERS (effects.rs)
**ContinuousEffect Struct:**
- source_id, controller, duration, layer, sub_layer (for P/T), timestamp, active
**Layer System (9 layers matching MTG rules 613):**
1. Copy effects
2. Control-changing
3. Text-changing
4. Type-changing
5. Color-changing
6. Ability-adding/removing
7. Power/toughness (7 sub-layers: CDA, Set, Modify, Counters, Switch)
8. Player effects
9. Rules effects
**EffectModification Enum:**
- CopyObject, ChangeControl, AddType, RemoveType, ChangeColor, AddKeyword, AddKeywordAll, SetBasePowerToughness, SetPowerToughness, ModifyPowerToughness, ModifyPowerToughnessAll, SwitchPowerToughness, PreventDamage, CantAttack, CantBlock, Custom
#### IMPLEMENTATION STATUS:
- **Layers defined but not fully applied**: The 7-layer system exists for data organization, but the game loop doesn't recalculate all layers after each modification
- **Timestamp ordering** implemented (effects within same layer ordered by creation time)
- **Expiration handling**: Effects with Duration::EndOfTurn removed in cleanup step
- **Type checking**: is_end_of_turn flag triggers removal
#### LIMITATIONS:
- No recalculation trigger after state changes
- No "recalculate characteristics" pass
- Simplification: boost effects use counters instead of continuous effects
---
### 12. REPLACEMENT EFFECTS (effects.rs)
**ReplacementEffect Struct:**
- source_id, controller, replaces (EventType), duration, active, replacement (kind)
**ReplacementKind Enum:**
- Prevent (block entirely)
- ExileInstead (instead of graveyard)
- ModifyAmount { delta: i32 } (e.g., double damage, prevent N)
- RedirectTarget { new_target }
- EnterTapped
- EnterWithCounters { counter_type, count }
- Custom(String)
#### IMPLEMENTATION STATUS:
- **Data structures defined but NOT integrated into game loop**
- No event interception mechanism in process_step()
- No replacement effect prompts to players
- Declared for future expansion but currently a no-op
---
### 13. PLAYER DECISION MAKING (decision.rs)
**PlayerDecisionMaker Trait Methods Defined:**
- **priority()** — Given legal_actions (vec of PlayerAction), return chosen action
- **choose_targets()** — Given legal targets, return selected ObjectIds
- **choose_mode()** — Given modal spell choices, return 0-indexed mode
- **choose_discard()** — Given hand cards + count, return cards to discard
- **choose_mulligan()** — Decide to mulligan or keep hand
- **choose_cards_to_put_back()** — London mulligan, pick cards to put on library bottom
- **choose_use()** — Yes/no decision (pay optional cost, etc.)
- **choose_order()** — Order a list of objects (scry, tutor, etc.)
**PlayerAction Enum:**
- Pass, CastSpell { card_id, targets, mode, without_mana }, PlayLand { card_id }, ActivateAbility { source_id, ability_id, targets }, ActivateManaAbility { source_id, ability_id }, SpecialAction { source_id, action_type }
**Implementations:**
- AlwaysPassPlayer: Passes all decisions
- DiscardingPlayer: Makes reasonable discard choices
- Heuristic AI in mtg-ai crate
---
### 14. COUNTER SYSTEM (counters.rs, permanent.rs)
**CounterType Enum (68 variants):**
#### Core:
- P1P1 (+1/+1), M1M1 (-1/-1)
#### Named:
- Loyalty (planeswalkers)
- Charge, Shield, Stun, Finality, Level, Lore, Time, Fade, Age, Storage, Divinity, Energy, Experience, Poison, Rad, Ticket
- Flying, FirstStrike, DoubleStrike, Deathtouch, Hexproof, Indestructible, Lifelink, Menace, Reach, Trample, Vigilance
- Bounty, Brick, Dream, Doom, Egg, Flood, Fungus, Growth, Hatchling, Ice, Luck, Mine, Page, Quest, Slime, Spore, Tower, Verse, Wish, Vitality, Valor, Training
- Custom(String)
**Counters Container:**
- HashMap (count per type)
- add(), remove(), clear() operations
- is_empty(), len()
**Permanent Fields:**
- counters: Counters
- add_counters(type, count) — adds to the map
- Has indestructibility check (granted_keywords | removed_keywords)
#### USAGE:
- **+1/+1 counters**: Used for all P/T boosts (simplification from continuous effects)
- **Summoning sickness**: Not a counter; tracked as perm.summoning_sick bool
- **Tapped state**: Not a counter; tracked as perm.tapped bool
- **Damage**: Not stored as counter; tracked as perm.damage u32
---
### 15. CARD & PERMANENT SYSTEM (card.rs, permanent.rs)
**CardData Struct:**
- id, owner, name, mana_cost, card_types, subtypes, supertypes
- power, toughness (Option)
- keywords (KeywordAbilities bitflags)
- abilities (Vec)
- text (rules text)
**Permanent Struct (wraps CardData):**
- card (CardData)
- controller (PlayerId) — can differ from owner
- tapped, summoning_sick, damage, counters
- granted_keywords, removed_keywords
- chosen_type (for "choose creature type" effects)
- original_controller (for GainControlUntilEndOfTurn reversal)
- zone_change_count
**Methods:**
- is_creature(), is_land(), is_artifact(), is_enchantment(), is_planeswalker()
- has_keyword(kw), has_flying(), has_haste(), has_defender(), has_reach()
- can_attack() — not tapped, not summoning sick, not land
- can_block() — not tapped, has reach/flying or blocker is flying
- apply_damage(amount) — marks damage on creature
- add_counters(type, count)
- power(), toughness() — current P/T including counters
---
### 16. ABILITY STORE & RESOLUTION (abilities.rs, game.rs)
**AbilityStore:**
- HashMap (all abilities)
- HashMap> (index by source)
- Methods: add(), get(), for_source(), triggered_by(), mana_abilities_for()
**Ability Types (from AbilityType enum):**
- PlayLand, Spell, Static, ActivatedNonMana, ActivatedMana, TriggeredNonMana, TriggeredMana, SpecialAction
**Ability Activation:**
- Activated abilities: player pays costs, chooses targets, resolves effects
- Triggered abilities: automatically put on stack (when integrated)
- Mana abilities: don't use stack, resolve immediately
- Static abilities: apply continuous effects passively
**Stack Resolution:**
- resolve_top_of_stack() pops spell/ability, resolves abilities, executes effects
- Targets validated at resolution
- State-based actions checked after resolution
---
### MISSING/TODO FEATURES
#### From game.rs TODO comments:
1. **Triggered abilities on stack** (task #13) — Events are queued but abilities not yet put on stack
2. **Combat tricks during declare** — Can't respond between declare attackers and blockers
3. **Replacement effect integration** — Declared but not hooked into event flow
4. **State-based action loop** — Simplified; doesn't handle all MTG rules
#### From code review:
1. **Hybrid mana** — Not modeled (would need {B/R} syntax support)
2. **Restricted mana** — "Spend only on creatures" not tracked
3. **Evoke enforcement** — Declared in StaticEffect but not enforced
4. **Ward enforcement** — No cost-paying system for ward taxes
5. **Flashback/Escape** — Cost types declared but not enforced
6. **Copy effects** — Layer 1 defined but no copy() for permanents
7. **Protection** — Listed as keyword but no enforcement
8. **Landwalk evasion** — Keywords declared but not checked in combat validation
9. **Shroud/Hexproof** — Not enforced for targeting (all targets are valid)
10. **Convoke/Delve/Cascade** — Keywords declared but no logic
11. **Storm/Storm effects** — Not implemented
12. **Mulligan variants** — Only London mulligan; no Traditional/Modern
13. **Choice between multiple decisions** — No multi-step targeting (e.g., "target creature, then target opponent")
---
### ARCHITECTURE STRENGTHS
1. **Data-oriented design** — Effects, costs, and abilities as enums with match arms (no inheritance)
2. **Serde serialization** — All core types implement Serialize/Deserialize for save/load
3. **Send + Sync everywhere** — Types verified at compile time for parallelism
4. **Layered organization** — Clear separation: game loop (game.rs) → effects (effects.rs) → abilities (abilities.rs)
5. **Filter system** — String-based filters (simple but extensible)
6. **Event logging** — Events tracked for triggered ability evaluation
7. **Timestamp ordering** — Continuous effects have proper dependency ordering
---
### PERFORMANCE NOTES
- **~88 games/sec** single-threaded with random AI
- **~585/sec** with rayon parallelism (6-8 worker threads)
- **Bottlenecks**: Card store lookups, filter matching, decision making (AI evaluation)
- **Optimization opportunities**: Cache filter matches, parallelize state-based action loops, batch effect resolution
---
### KEY FILES BY FUNCTION
| File | Lines | Purpose |
|------|-------|---------|
| game.rs | ~1200 | Main game loop, turn structure, priority system, effect resolution |
| abilities.rs | ~1623 | Effect/Cost/StaticEffect/Ability definitions + builders |
| effects.rs | ~542 | Continuous effects, 7-layer system, replacement effects |
| events.rs | ~753 | Event types, GameEvent struct, event builder methods |
| decision.rs | ~400+ | PlayerDecisionMaker trait, PlayerAction enum, GameView |
| state.rs | ~800+ | GameState struct, battlefield, zones, player storage |
| combat.rs | ~250+ | CombatState, CombatGroup, validation logic |
| permanent.rs | ~400+ | Permanent struct, keyword checks, P/T calculation |
| card.rs | ~200+ | CardData struct, card type checks |
| mana.rs | ~300+ | Mana struct, cost parsing, payment validation |
| constants.rs | ~910 | Zone, PhaseStep, CardType, Color, SubType, KeywordAbilities, Layer/SubLayer |
| zones.rs | ~300+ | Library, Hand, Graveyard, Exile, Battlefield, Stack containers |
| counters.rs | ~250+ | CounterType enum, Counters container |
---
This completes the comprehensive catalog of the mtg-rl engine. The implementation is **functionally complete for basic gameplay** (casting spells, activating abilities, combat, life gain/loss, drawing cards), but **lacks advanced features** like triggered ability stacking, replacement effect interception, and proper continuous effect layer recalculation.
total_tokens: 114137
tool_uses: 25
duration_ms: 114113
Full transcript available at: /tmp/claude-1000/-mnt-dest-btrfs-home-jc-src-mage/tasks/ac21389.output
## Assistant
Good, the Rust engine inventory is complete. Two agents done, two still running. Let me check on the remaining two.
## Assistant
### Tool: TaskOutput
**Args:**
```json
{
"block": false,
"task_id": "a2b068c",
"timeout": 5000
}
```
## Assistant
**Result** (success):
```
not_ready
a2b068c
local_agent
running
```
## Assistant
### Tool: TaskOutput
**Args:**
```json
{
"block": false,
"task_id": "a715424",
"timeout": 5000
}
```
## Assistant
**Result** (success):
```
not_ready
a715424
local_agent
running
```
## Assistant
The Java engine agent is still working and the Custom effects agent is wrapping up. I can see from partial output that there are 940 total Custom usages across all sets (747 Effect::Custom, 160 StaticEffect::Custom, 33 Cost::Custom). Let me wait for both to finish.
## User
a715424
completed
Agent "Catalog Custom effects in card sets" completed
Excellent! Now let me create a final summary document with the key findings and create a comprehensive catalog:
## RUST CARD IMPLEMENTATIONS CUSTOM USAGE ANALYSIS
### Executive Summary
Across the 4 Rust card sets (FDN, TLA, TDM, ECL), there are **940 total Custom fallback usages** distributed as follows:
**By Type:**
- **Effect::Custom**: 747 (79.5%)
- **StaticEffect::Custom**: 160 (17.0%)
- **Cost::Custom**: 33 (3.5%)
**By Set:**
- **FDN** (Foundations): 401 customs (322 Effect + 58 Static + 21 Cost)
- **TLA** (Avatar: The Last Airbender): 253 customs (197 Effect + 54 Static + 2 Cost)
- **ECL** (Eclogue): 156 customs (117 Effect + 32 Static + 7 Cost)
- **TDM** (Tolkien): 130 customs (111 Effect + 16 Static + 3 Cost)
---
## EFFECT::CUSTOM ANALYSIS (747 total)
### Top Categories by Volume
| Category | Count | Key Patterns |
|----------|-------|--------------|
| **Generic/Placeholder** | 355 | "ETB effect", "Activated effect", "Spell effect", etc. — mostly stub implementations |
| **ETB/Enter Effects** | 122 | "ETB effect" (79), Saga mechanics (6), conditional ETB abilities (37) |
| **Activated Abilities** | 67 | Generic "Activated effect" — all 67 cards need proper activation logic |
| **Cast/Spell Triggers** | 47 | Cost reduction (6), flashback/graveyard casting (6), trigger modifiers (35) |
| **Attack/Combat Triggers** | 45 | Combat damage triggers (21), combat phase effects (24) |
| **Attach/Enchant Effects** | 28 | Auras and equipment attachment mechanics |
| **Exile/Play From** | 25 | Exile mechanics, cascade-like effects, suspend, "play cards exiled" |
| **Spell Effects** | 21 | Generic spell mechanics placeholder |
| **Dies/Sacrifice** | 18 | Death triggers, sacrifice effects (11) |
| **Tapped/Untap** | 10 | Tapped mechanics, land tutoring with tapped keyword |
| **Earthbend/Keywords** | 5 | TLA-specific custom keywords (Earthbend 1-2) |
| **Cost Modifiers** | 4 | Cost reduction based on game state |
### Top 20 Most Common Effect::Custom Patterns
1. **90x "Static effect"** — Placeholder for complex static effects across all sets
2. **79x "ETB effect"** — Cards that trigger on enter the battlefield
3. **67x "Activated effect"** — Cards with activated abilities needing proper implementation
4. **21x "Spell effect"** — Generic spell mechanics
5. **21x "Attack trigger"** — Combat-related triggers
6. **14x "Spell cast trigger"** — Casting-related mechanics
7. **11x "Attach to target creature you control"** — Aura/Equipment attachment
8. **11x "Dies effect"** — Death triggers
9. **6x "Saga mechanics"** — Enchantment Saga cards
10. **4x "Return exiled card to hand"** — Exile recursion mechanics
11. **3x "Tapped trigger"** — Tapped-creature mechanics
12. **3x "Cast from graveyard, then exile"** — Flashback/exile mechanics
13. **3x "Cast from graveyard"** — Pure graveyard casting
14. **2x "Each opponent loses 1 life"** — Opponent life loss
15. **2x "Creatures you control gain trample"** — Evasion grants
16. **2x "Draw second card trigger"** — Card draw triggers
17. **2x "Enchant creature"** — Aura enchantment
18. **1x each** — 200+ unique specific mechanics
### Notable Effect::Custom Patterns Requiring Engine Implementation
**Modal/Choice Mechanics:**
- "Choose one:" options (20+ patterns)
- "Choose Jeskai/Mardu" modal selections
**Complex Conditional Effects:**
- "Threshold: +2/+1 if graveyard >= 7"
- "Conditional +2/+2 if life >= 25"
- "Conditional +2/+0 if another creature ETB'd this turn"
**X-Cost Effects:**
- "Creatures you control get +X/+X and trample until end of turn, X = creatures you control"
- "Create X 1/1 white Soldier creature tokens, where X = the number of creature cards in your graveyard"
- "Distribution: three +1/+1 counters among one, two, or three target creatures"
**Copy/Token Mechanics:**
- "Create a token that's a copy of target creature"
- "Copy the next spell you cast this turn"
- "Conspire: tap two creatures to copy spell"
**Graveyard/Exile Mechanics:**
- "Exile top card, play until next end step"
- "Cast from graveyard, then exile"
- "Cast exiled creatures by removing 3 counters"
**Saga Mechanics:**
- "(As this Saga enters and after your draw step, add a lore counter. Sacrifice after III.)" — 6 instances
**Combat/Evasion:**
- "This creature can't be blocked" / "Can't be blocked by Humans" / "Daunt — can't be blocked by power 2 or less"
- "Attacks each combat if able"
- "Additional combat phase"
---
## STATICEFFECT::CUSTOM ANALYSIS (160 total)
### By Category
| Category | Count | Key Patterns |
|----------|-------|--------------|
| **Generic/Placeholder** | 94 | "Static effect" (90), "Conditional continuous effect" (4) |
| **Other** | 14 | Misc mechanics (affinity, deck restrictions, etc.) |
| **P/T Modification** | 11 | Conditional boosts, lord effects |
| **Counter/Spell Protection** | 8 | Can't be countered, counter manipulation |
| **Evasion/Block Restrictions** | 5 | Daunt, block restrictions, shadow-like effects |
| **Protection Effects** | 4 | Hexproof, protection from colors |
| **Keyword Grant** | 4 | Flash conditional, haste conditional |
| **Damage/Prevention** | 4 | Damage assignment, damage prevention |
| **Keyword Abilities** | 4 | Kicker, Convoke, Delve as static effects |
| **Transform/Copy** | 3 | Transform mechanics, copy effects |
| **Mana/Land Effects** | 3 | Additional land drops, mana doubling |
| **Cost Reduction** | 2 | Cost reduction based on conditions |
| **Enter/ETB Effects** | 1 | Enters tapped mechanics |
| **Ward/Tax Effects** | 1 | Ward keyword |
| **Token Creation** | 1 | Token doubling |
| **Trigger Modifiers** | 1 | Trigger multipliers |
### Notable StaticEffect::Custom Patterns
**High-Impact Missing Features (1 card each, but critical):**
- **Delve** — "Spells you cast have delve"
- **Convoke** — "Creature spells you cast have convoke"
- **Flash conditional** — "Flash if you control a Faerie"
- **Affinity** — "Affinity for allies"
- **Damage assignment** — "Assigns combat damage equal to toughness"
- **Mana doubling** — "Basic land mana doubling"
- **Trigger multiplier** — "Other Elementals' triggered abilities trigger an additional time"
**Protection & Evasion (5 cards):**
- "Hexproof as long as untapped"
- "Can't be blocked by more than one creature"
- "Daunt — can't be blocked by power 2 or less"
- "Threshold — creature can't be blocked if graveyard >= 7"
- "Can't be blocked by Humans"
**P/T Modification (11 cards):**
- Dynamic P/T based on game state
- "+X/+X where X = [condition]" patterns
- "Power = colors among your permanents"
- "Gets +X/+X per [resource]"
---
## COST::CUSTOM ANALYSIS (33 total)
All Cost::Custom usages represent activated abilities or costs that don't fit the engine's Cost enum. Breakdown:
| Category | Count | Examples |
|----------|-------|----------|
| **Mana/Tap Costs** | 13 | Complex mana abilities: "{T}: Add {C}{C}", "{2}{G}{G}: Put X counters" |
| **Sacrifice Costs** | 9 | "{X}, Sacrifice: [effect]" patterns (search library, destroy, draw, etc.) |
| **Tap Creature Costs** | 5 | "Tap 3 untapped creatures you control", "Tap another untapped creature" |
| **Exile Costs** | 3 | "Exile this card from graveyard", "Exile this enchantment" |
| **Complex Multi-Part** | 2 | "{8}: Create 4/4 Dragon token", "{T}: Create X 1/1 tokens where X = [condition]" |
| **Discard Costs** | 1 | "Discard your hand" |
### Notable Cost::Custom Patterns
**Multi-Step Search Abilities:**
- "{3}, Sacrifice Burnished Hart: Search your library for up to two basic land cards, put them onto the battlefield tapped"
- "{4}{G}{G}, {T}: Look at top six cards. You may reveal a creature card with MV <= lands you control"
- "{2}{W}: Look at top four cards. You may reveal a creature card with power 2 or less"
**Complex Tap Abilities:**
- "Tap creatures with total power 3+"
- "Tap three untapped creatures you control"
**Land Abilities:**
- "{4}: This land becomes a 3/3 creature with vigilance and all creature types. It's still a land"
- "{4}: Put two +1/+1 counters on this land. Then you may have it become a 0/0 Elemental until end of turn. It's still a land"
**Draw/Sacrifice Combos:**
- "{1}, {T}, Sacrifice a creature: Draw a card and put a soul counter on this artifact"
- "{1}{B}, Sacrifice a creature: You gain 1 life and draw a card"
---
## CATEGORIZED ENGINE FEATURE GAPS
Based on the Custom patterns analysis, here are the **highest-priority missing engine features** by impact:
### CRITICAL (Would eliminate 100+ customs each)
1. **Proper ETB Effect Framework** (122 customs)
- Current: 79 generic "ETB effect" stubs
- Need: `Effect::EntersBattlefield { effect: Box }`
2. **Modal Spells / Choice Mechanics** (20+ customs)
- Modes like "Choose one:" or "Choose two:"
- Affects FDN heavily
3. **Activated Ability Framework** (67+ customs)
- Generic "Activated effect" stubs need proper cost+effect binding
- Need better DSL for common patterns
### HIGH (Would eliminate 20-100 customs each)
4. **Combat Trigger Framework** (45 customs)
- Attack triggers, combat phase effects
- Includes raid, exalted, etc.
5. **Conditional/State-Based Effects** (30+ customs)
- "Power = X", "Cost reduction if condition"
- "+X/+X where X = [game state]"
6. **Graveyard Casting & Exile Management** (25 customs)
- Flashback, Escape, Suspend mechanics
- "Exile top card, play until next end step"
7. **Spell/Cast Triggers** (47 customs)
- Cost reduction for casting
- Triggers when spells are cast
8. **Copy & Token Creation** (20+ customs)
- "Create a token copy of target creature"
- "Copy this spell"
### MEDIUM (Would eliminate 10-20 customs each)
9. **Saga Mechanics** (6 customs)
- Enchantment subtypes with lore counters
- All TLA/TDM exclusive
10. **Die/Sacrifice Triggers** (18 customs)
- Morbid, aristocrat mechanics
11. **Aura/Equipment Attachment** (28 customs)
- Proper enchant target binding
12. **Keyword Ability Grants** (15+ customs)
- "Grant [keyword] until end of turn"
- Conditional flash, haste, etc.
### LOWER (Single-digit impact each but notable)
13. **Delve/Convoke/Affinity** (4 customs)
- Set-specific keywords as static effects
14. **Ward/Tax Effects** (2 customs)
- Ward keyword, tax mechanics
15. **Transform Mechanics** (3 customs)
- Double-faced card behavior
16. **Trigger Multipliers** (1 custom)
- "Other [type] triggers an additional time"
17. **X-Cost Effects** (Several)
- Distribute counters, X-based P/T, etc.
18. **Mana Doubling / Land Effects** (3 customs)
- "Basic land mana doubling", "+1 land drop"
---
## SET-SPECIFIC INSIGHTS
**FDN (Foundations) - 401 customs:**
- Heaviest custom usage (42.7% of total)
- 322 Effect customs: ETB stubs (37+), activated ability stubs (20+)
- 58 Static customs: Many "Static effect" placeholders
- 21 Cost customs: Land abilities, complex tutors dominate
- Most common: Generic ETB/Activated/Spell effect stubs
- **Challenge**: Diverse mechanic set; many one-off abilities
**TLA (Avatar: The Last Airbender) - 253 customs:**
- 197 Effect customs: Mostly stubs (ETB 44, Activated 43, Spell cast 7)
- 54 Static customs: "Static effect" placeholders heavy
- 2 Cost customs: Minimal
- **Unique**: Earthbend (5 customs) — custom keyword mechanic not in engine
- **Challenge**: Avatar-specific keywords and mechanics
**TDM (Tolkien) - 130 customs:**
- 111 Effect customs: More variety than TLA/FDN stubs
- 16 Static customs: Fewer placeholder stubs
- 3 Cost customs: Minimal
- **Cleaner**: Higher proportion of specific mechanics vs. stubs
- **Challenge**: Dragon-focused mechanics, Saga support needed
**ECL (Eclogue) - 156 customs:**
- 117 Effect customs: Good mix of specific patterns
- 32 Static customs: More descriptive than stubs
- 7 Cost customs: Highest ratio for a set
- **Cleaner**: Most specific mechanics, fewest stubs
- **Challenge**: Hybrid mechanic set with lords, copy effects, triggers
---
## RECOMMENDATIONS FOR PRIORITIZATION
### Phase 1: Eliminate Generic Stubs (220+ customs)
- Implement proper ETB Effect framework
- Add proper Activated ability binding
- Removes: 90 "Static effect" + 79 "ETB effect" + 67 "Activated effect" + 21 "Spell effect"
### Phase 2: Combat & Trigger Frameworks (65+ customs)
- Combat trigger (attack, assign, damage)
- Cast/spell trigger mechanics
- Dies/sacrifice triggers
- Removes: 45 attack + 47 cast + 18 dies
### Phase 3: Condition & State-Based Effects (50+ customs)
- Dynamic P/T based on game state
- Cost reduction conditions
- Conditional granting
- Removes: 30+ conditional patterns
### Phase 4: Mechanic-Specific Features (30+ customs)
- Modal spells / choices
- Copy/token creation
- Graveyard/exile play
- Saga mechanics
### Phase 5: Keywords & Edge Cases (25+ customs)
- Delve, Convoke, Affinity
- Ward, Protection from X
- Keyword grants
- Transform mechanics
---
## TARGETSPEC & DECISION PATTERNS
From the analysis, the most common TargetSpec patterns in Custom effects are:
- **Target creature** (most common)
- **Target opponent**
- **Target player**
- **Target nonland permanent**
- **Target creature or planeswalker**
- **Target artifact or enchantment**
Most decision makers appear to be:
- **AlwaysPassPlayer** (for many generic stubs)
- **AlwaysChoosePredicate** (for automatic effects)
- **Custom decision logic** (needed for modal choices)
---
This analysis demonstrates that **the engine currently lacks ~940 implemented features** across spell/ability/cost mechanics, with the largest opportunity being the elimination of ~220 generic placeholder stubs via proper framework implementations.
total_tokens: 62447
tool_uses: 18
duration_ms: 98767
Full transcript available at: /tmp/claude-1000/-mnt-dest-btrfs-home-jc-src-mage/tasks/a715424.output
## Assistant
Good, three agents done. Let me wait for the Java engine exploration to complete.
## Assistant
### Tool: TaskOutput
**Args:**
```json
{
"block": true,
"task_id": "a2b068c",
"timeout": 120000
}
```
## Assistant
**Result** (success):
```
success
a2b068c
local_agent
completed
```
## Assistant
## Assistant
All four research agents are complete. Now I have comprehensive data to synthesize. Let me read the current ROADMAP.md one more time before rewriting it.
## Assistant
### Tool: Read
**Args:**
```json
{
"file_path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/ROADMAP.md"
}
```
## Assistant
**Result** (success):
```
1→# Roadmap
2→
3→This document describes implementation gaps in the mtg-rl engine and cards, organized by priority. Each engine feature lists how many cards it would unblock when implemented.
4→
5→## Engine Gaps
6→
7→### Effect Variants (game.rs `execute_effects()`)
8→
9→These `Effect` enum variants exist in `abilities.rs` but have no implementation in `execute_effects()` -- they fall through to `_ => {}` and silently do nothing at runtime.
10→
11→**Recently implemented:** The following Effect variants were previously no-ops but now have working implementations in `execute_effects()`: `Scry`, `SearchLibrary`, `ReturnFromGraveyard`, `Reanimate`, `GainKeywordUntilEndOfTurn`, `GainKeyword`, `LoseKeyword`, `Indestructible`, `Hexproof`, `CantBlock`, `Sacrifice`, `DestroyAll`, `DealDamageAll`, `RemoveCounters`, `CreateTokenTappedAttacking`, `BoostPermanent`, `SetPowerToughness`, `LoseLifeOpponents`, `LookTopAndPick`, `PutOnLibrary`, `GainControl`, `GainControlUntilEndOfTurn`. Modal spells with `Effect::Modal` variant now functional, token stat parsing is also implemented (`CreateToken` now parses P/T and keywords from `token_name`).
12→
13→**Batch 2 engine change (2026-02-13):** Modified `execute_effects` to accept an optional `source: Option` parameter. When `AddCounters` or `RemoveCounters` effects have no selected targets, they now fall back to the source permanent. This enables self-targeting counter effects (e.g., blight creatures putting -1/-1 counters on themselves) without requiring explicit target selection. Test: `add_counters_self_when_no_targets`.
14→
15→**Batch 5 (2026-02-13):** Added `StaticEffect::Ward { cost: String }` variant + `ward()` builder. Ward is a triggered ability that counters targeting spells/abilities unless the opponent pays the cost. The engine stores it as structured data (not yet mechanically enforced during targeting). Replaced `StaticEffect::Custom("Ward ...")` on 7 cards across FDN/TDM/ECL and added `KeywordAbilities::WARD` flags.
16→
17→**Batch 6 (2026-02-13):** Added `StaticEffect::EntersTappedUnless { condition: String }` variant + `enters_tapped_unless()` builder. Stored as structured data; mechanical enforcement deferred. Replaced `StaticEffect::Custom("Enters tapped unless ...")` on 2 TDM lands (Cori Mountain Monastery, Dalkovan Encampment).
18→
19→**Batch 7 (2026-02-13):** Added `Effect::BoostAllUntilEndOfTurn { filter, power, toughness }` and `Effect::GrantKeywordAllUntilEndOfTurn { filter, keyword }` variants with constructors and match arms. These mass-buff effects apply to all creatures matching the filter controlled by the effect's controller. Replaced Custom effects on 8 cards (6 FDN, 2 ECL) with 12 effect swaps total.
20→
21→**Batch 9 (2026-02-13):** Added `Effect::AddCountersAll { counter_type, count, filter }` variant + `add_counters_all()` constructor + match arm. Puts N counters of specified type on all creatures matching filter, with "you control" support. Fixed ECL Darkness Descends and partially fixed TDM Barrensteppe Siege (Abzan mode only).
22→
23→**Batch 10 (2026-02-14):** Added `Effect::AddCountersSelf { counter_type, count }` variant + `add_counters_self()` constructor + match arm. Unlike `AddCounters` (source fallback only when targets empty), `AddCountersSelf` always applies to the source permanent regardless of other targets. Enables compound effects like "blight self + grant haste to target creature" (Warren Torchmaster).
24→
25→**Cost System (2026-02-14):** Implemented `pay_costs()` match arms for `RemoveCounters` (remove typed counters from source), `Blight` (add -1/-1 counters to source), `ExileFromGraveyard` (exile N cards from graveyard), `ExileFromHand` (exile N cards from hand), `SacrificeOther` (sacrifice another permanent matching filter), `UntapSelf` (untap cost), and `Custom` (no-op annotation). Previously these costs silently passed through the catch-all. 6 tests added.
26→
27→**Vivid Mechanic (2026-02-14):** Added `count_colors_among_permanents()` helper that counts distinct colors (0-5) among permanents a player controls. Added 6 Vivid effect variants: `DealDamageVivid`, `GainLifeVivid`, `BoostUntilEotVivid`, `LoseLifeOpponentsVivid`, `DrawCardsVivid`, `BoostAllUntilEotVivid`. Updated 6 ECL cards (Explosive Prodigy, Glister Bairn, Luminollusk, Shimmercreep, Shinestriker, Prismabasher) with typed Vivid effects. 5 tests added.
28→
29→| Effect Variant | Description | Cards Blocked |
30→|---------------|-------------|---------------|
31→| `GainProtection` | Target gains protection from quality | ~5 |
32→| `PreventCombatDamage` | Fog / damage prevention | ~5 |
33→| `MustBlock` | Target creature must block | ~3 |
34→| `SetLife` | Set a player's life total | ~2 |
35→| `Custom(String)` | Catch-all for untyped effects | ~400+ |
36→
37→Note: `Custom(String)` is used when no typed variant exists. Each Custom needs to be individually replaced with a typed variant or a new variant added.
38→
39→### Static Effect Enforcement
40→
41→`StaticEffect` variants (`Boost`, `GrantKeyword`, `CantBlock`, `CantAttack`, `CostReduction`, `Ward`, `EntersTappedUnless`, `EntersTapped`, `CantGainLife`, `CantDrawExtraCards`) are currently **structured annotations only** — `game.rs` never reads or applies them. In Java XMage, these are active participants in the game loop via the continuous effects layer system (7 layers: Copy → Control → Text → Type → Color → Ability → P/T).
42→
43→To make them functional, we need:
44→1. **Continuous effect application loop** in `game.rs` that iterates battlefield permanents' `static_effects` each time state-based actions are checked
45→2. **ETB replacement hooks** for `EntersTappedUnless` (ask player to pay, conditionally tap)
46→3. **Combat restriction enforcement** for `CantAttack` / `CantBlock` during declare attackers/blockers
47→4. **P/T modification layer** for `Boost` (lord effects) applied as a layer on top of base stats
48→5. **Keyword granting** for `GrantKeyword` applied during ability checks
49→
50→This is a significant but high-ROI engine change — it would make ~50+ lord effects, combat restrictions, and ETB conditions functional across all sets.
51→
52→### Missing Engine Systems
53→
54→These are features that require new engine architecture, not just new match arms:
55→
56→#### Equipment System
57→- No attach/detach mechanics
58→- Equipment stat bonuses not applied
59→- Equip cost not evaluated
60→- **Blocked cards:** Basilisk Collar, Swiftfoot Boots, Goldvein Pick, Fishing Pole, all Equipment (~15+ cards)
61→
62→#### Planeswalker System
63→- Loyalty counters not tracked as a resource
64→- Planeswalker abilities not resolved (loyalty cost/gain)
65→- Planeswalker damage redirection not enforced
66→- **Blocked cards:** Ajani, Chandra, Kaito, Liliana, Vivien, all planeswalkers (~10+ cards)
67→
68→#### ~~Modal Spells~~ (DONE)
69→`Effect::Modal { modes, min_modes, max_modes }` + `ModalMode` struct. Player selects modes via `choose_mode()`, then each chosen mode's effects execute in order. Supports "choose one", "choose two", "choose one or both" patterns. Fixed 7 ECL command/modal cards.
70→
71→#### X-Cost Spells
72→- No variable cost determination
73→- X is not tracked or passed to effects
74→- **Blocked cards:** Day of Black Sun, Spectral Denial (partially works), Genesis Wave, Finale of Revelation (~10+ cards)
75→
76→#### ~~Fight/Bite Mechanic~~ (DONE)
77→`Effect::Fight` (mutual damage) and `Effect::Bite` (one-way damage) implemented with proper two-target selection via `TargetSpec::Pair { CreatureYouControl, OpponentCreature }`. Matches Java's `FightTargetsEffect` / `DamageWithPowerFromOneToAnotherTargetEffect` pattern. Compound effects (e.g. +1/+1 counter then bite) correctly apply pre-fight/bite effects only to `targets[0]` (your creature). Fixed 6 cards (Bite Down, Affectionate Indrik, Felling Blow, Knockout Maneuver, Piercing Exhale, Assert Perfection). ETB triggers (Affectionate Indrik) use `TargetSpec::OpponentCreature` with source as fighter. Remaining fight/bite cards blocked by modal spells (Batch 11), X-cost (Batch 15), or other missing systems.
78→
79→#### ~~Token Stat Parsing~~ (DONE)
80→`CreateToken` now parses P/T and keywords from `token_name` strings (e.g., '4/4 Dragon with flying' creates a 4/4 with flying). Cards using correctly-formatted token names now work.
81→
82→#### Aura/Enchant System
83→- Auras exist as permanents but don't attach to creatures
84→- Static P/T boosts from Auras not applied
85→- Keyword grants from Auras not applied
86→- **Blocked cards:** Pacifism (partially works via CantAttack/CantBlock), Obsessive Pursuit, Eaten by Piranhas, Angelic Destiny (~10+ cards)
87→
88→#### Impulse Draw (Exile-and-Play)
89→- "Exile top card, you may play it until end of [next] turn" has no implementation
90→- **Blocked cards:** Equilibrium Adept, Kulrath Zealot, Sizzling Changeling, Burning Curiosity, Etali (~10+ cards)
91→
92→#### Spell Copy
93→- No mechanism to copy spells on the stack
94→- **Blocked cards:** Electroduplicate, Rite of Replication, Self-Reflection, Flamehold Grappler, Sage of the Skies (~8+ cards)
95→
96→#### Replacement Effects
97→- `ReplacementEffect` struct exists in `effects.rs` but is not integrated into the event pipeline
98→- Events are not interceptable before they resolve
99→- **Blocked features:** "If a creature would die, exile it instead", "If you would gain life, gain that much +1", Doubling Season, damage prevention, Dryad Militant graveyard replacement
100→
101→#### Additional Combat Phases
102→- No support for extra combat steps
103→- **Blocked cards:** Aurelia the Warleader, All-Out Assault (~3 cards)
104→
105→#### "Behold" Mechanic (ECL-specific)
106→- Reveal-and-exile-from-hand mechanic not implemented
107→- Many ECL cards reference it as an alternative cost or condition
108→- **Blocked cards:** Champion of the Weird, Champions of the Perfect, Molten Exhale, Osseous Exhale (~15+ cards)
109→
110→#### "Earthbend" Mechanic (TLA-specific)
111→- "Look at top N, put a land to hand, rest on bottom" not implemented
112→- **Blocked cards:** Badgermole, Badgermole Cub, Ostrich-Horse, Dai Li Agents, Earth Kingdom General, Earth Village Ruffians, many TLA cards (~20+ cards)
113→
114→#### "Vivid" Mechanic (ECL-specific)
115→- "X = number of colors among permanents you control" calculation not implemented
116→- **Blocked cards:** Explosive Prodigy, Glister Bairn, Luminollusk, Prismabasher, Shimmercreep, Shinestriker, Squawkroaster (~10+ cards)
117→
118→#### Delayed Triggers
119→- "When this creature dies this turn, draw a card" style effects
120→- No framework for registering one-shot triggered abilities
121→- **Blocked cards:** Undying Malice, Fake Your Own Death, Desperate Measures, Scarblades Malice (~5+ cards)
122→
123→#### Conditional Cost Modifications
124→- `CostReduction` static effect exists but may not apply correctly
125→- No support for "second spell costs {1} less" or Affinity
126→- **Blocked cards:** Highspire Bell-Ringer, Allies at Last, Ghalta Primal Hunger (~5+ cards)
127→
128→---
129→
130→## Phased Implementation Plan
131→
132→### Phase 1: High-Impact Engine Effects
133→
134→These unblock the most cards per effort invested.
135→
136→1. **Token stat parsing** -- **DONE** -- Parse power/toughness/keywords from `token_name` string in `CreateToken`. Unblocks ~30 cards that already create tokens but with wrong stats.
137→
138→2. **Fix easy card-level bugs** -- Many cards use `Effect::Custom(...)` when a typed variant already exists. Examples:
139→ - ~~Phyrexian Arena: `Custom("You lose 1 life.")` -> `LoseLife { amount: 1 }`~~ **DONE**
140→ - ~~Pulse Tracker/Marauding Blight-Priest/Vampire Spawn/Vampire Neonate: `Custom("Each opponent loses N life")` -> `LoseLifeOpponents { amount: N }`~~ **DONE**
141→ - ~~Skirmish Rhino (TDM), Champion of the Weird (ECL), Boggart Mischief (ECL): opponent life loss Custom -> `LoseLifeOpponents`~~ **DONE**
142→ - ~~Diregraf Ghoul: `StaticEffect::Custom("Enters tapped.")` -> `StaticEffect::EntersTapped`~~ **DONE**
143→ - Incomplete dual lands: copy the Azorius Guildgate / Bloodfell Caves pattern
144→ - ~~Sourbread Auntie/Sting-Slinger/Blighted Blackthorn: self-counter Custom -> `AddCounters` targeting self~~ **DONE**
145→ - ~~Day of Judgment: `Custom("Destroy all creatures.")` -> `DestroyAll`~~ **DONE**
146→ - ~~Frenzied Goblin/Brambleback Brute: `Custom("can't block")` -> `CantBlock`~~ **DONE**
147→ - ~~Icewind Elemental/Refute: loot/counter Custom -> typed effects~~ **DONE**
148→ - ~~ECL RemoveCounters cards (Encumbered Reejerey, Reluctant Dounguard, Heirloom Auntie, Bristlebane Battler): Custom -> `RemoveCounters` with source fallback~~ **DONE**
149→ - ~~Mistmeadow Council: Custom -> `draw_cards(1)`~~ **DONE**
150→ - ~~Guarded Heir, Prideful Parent, Resolute Reinforcements, Release the Dogs, Dwynen's Elite, Dragonmaster Outcast, Searslicer Goblin: token creation Custom -> `create_token()`~~ **DONE**
151→ - ~~Clachan Festival (ECL): token creation Custom + Cost::Custom -> `create_token()` + `Cost::pay_mana()`~~ **DONE**
152→ - ~~Burglar Rat/Dream Seizer/Arbiter of Woe/Bloodtithe Collector: opponent discard Custom -> `DiscardOpponents { count }`~~ **DONE**
153→ - ~~Warren Torchmaster: compound blight self + target haste Custom -> `AddCountersSelf` + `GainKeywordUntilEndOfTurn`~~ **DONE**
154→
155→3. ~~**Fight mechanic** -- New `Effect::Fight` and `Effect::Bite` variants. Fight = mutual damage, Bite = one-way. Fixed 6 cards.~~ **PARTIAL** — auto-selects strongest creature instead of player choice (needs multi-target `TargetSpec`). ETB triggers correct; spell-based is heuristic.
156→
157→### Phase 2: Key Missing Mechanics
158→
159→4. **Equipment system** -- Attach/detach, equip cost, stat/keyword application. Unblocks ~15 cards.
160→
161→5. **Modal spells** -- Mode selection in `PlayerDecisionMaker` trait, mode-conditional effect resolution. Unblocks ~20 cards.
162→
163→6. **Impulse draw** -- "Exile top N, may play until end of [next] turn." Track exiled-playable cards in game state. Unblocks ~10 cards.
164→
165→7. **Earthbend** (TLA-specific) -- "Look at top N, put a land to hand, rest on bottom." Unblocks ~20 TLA cards.
166→
167→### Phase 3: Advanced Systems
168→
169→8. **Replacement effects** -- Event interception pipeline. Required for damage prevention, death replacement, Doubling Season, "exile instead of dying."
170→
171→9. **X-cost spells** -- Variable cost determination + passing X to effects.
172→
173→10. **Aura attachment** -- Auras attach to targets, apply continuous effects while attached.
174→
175→11. **Spell copy** -- Clone spells on the stack with new targets.
176→
177→12. **Planeswalker system** -- Loyalty as a resource, planeswalker abilities, damage redirection.
178→
179→13. **Additional combat phases** -- Extra attack steps.
180→
181→### Phase 4: Set-Specific Mechanics
182→
183→14. **Behold** (ECL) -- Reveal-from-hand alternative cost/condition.
184→15. **Vivid** (ECL) -- Color-count calculation for dynamic X values.
185→16. **Learn** (TLA) -- May discard to draw keyword action.
186→17. **Renew** (TDM) -- Counter-based death replacement.
187→18. **Mobilize** (TDM) -- Create N 1/1 Soldier tokens. (Partially works via `CreateToken` already.)
188→
189→---
190→
191→## Per-Set Status
192→
193→Detailed per-card breakdowns with fix instructions are in `docs/`:
194→
195→| File | Set | Complete | Partial | Stub |
196→|------|-----|----------|---------|------|
197→| `docs/fdn-remediation.md` | Foundations | 95 | 126 | 267 |
198→| `docs/tla-remediation.md` | Avatar: TLA | 39 | 22 | 219 |
199→| `docs/tdm-remediation.md` | Tarkir: Dragonstorm | 97 | 115 | 59 |
200→| `docs/ecl-remediation.md` | Lorwyn Eclipsed | 56 | 69 | 105 |
201→
202→*Note: These counts are outdated -- see the individual remediation docs for current status.*
203→
204→Each remediation doc includes:
205→- Full card-by-card audit with working vs broken effects
206→- Java source file references for each card
207→- Specific fix instructions per card
208→- Priority remediation roadmap for that set
209→
```
## Assistant
## Assistant
Let me verify one critical claim from the keyword agent - whether combat is actually missing from the game loop.
## Assistant
### Tool: Grep
**Args:**
```json
{
"output_mode": "content",
"path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/game.rs",
"pattern": "PhaseStep::"
}
```
## Assistant
**Result** (success):
```
222: self.state.current_step = PhaseStep::Untap;
365: PhaseStep::Untap => {
379: PhaseStep::Draw => {
386: PhaseStep::Cleanup => {
```
## Assistant
### Tool: Grep
**Args:**
```json
{
"-C": 3,
"output_mode": "content",
"path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/game.rs",
"pattern": "fn process_step|fn execute_turn|TURN_STEPS|fn run_game|PHASE_STEPS"
}
```
## Assistant
**Result** (success):
```
340- }
341-
342- / Process the current step: turn-based actions, SBAs, triggers, priority.
343: fn process_step(&mut self) {
344- let step = self.state.current_step;
345- let active = self.state.active_player;
346-
```
## Assistant
## Assistant
### Tool: Read
**Args:**
```json
{
"file_path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/game.rs",
"limit": 70,
"offset": 200
}
```
## Assistant
**Result** (success):
```
200→
201→ // Advance to next step
202→ match self.turn_manager.advance_step() {
203→ Some(step) => {
204→ // Empty mana pools at phase transitions
205→ let old_phase = self.state.current_step.phase();
206→ let new_phase = step.phase();
207→ if old_phase != new_phase {
208→ for player in self.state.players.values_mut() {
209→ player.mana_pool.clear();
210→ }
211→ }
212→
213→ self.state.current_step = step;
214→ self.state.current_phase = self.turn_manager.current_phase();
215→ }
216→ None => {
217→ // Turn is over, start next turn
218→ let next_active = self.turn_manager.next_turn();
219→ self.state.turn_number = self.turn_manager.turn_number;
220→ self.state.active_player = next_active;
221→ self.state.priority_player = next_active;
222→ self.state.current_step = PhaseStep::Untap;
223→ self.state.current_phase = self.turn_manager.current_phase();
224→
225→ // Reset per-turn state for active player
226→ if let Some(player) = self.state.players.get_mut(&next_active) {
227→ player.begin_turn();
228→ }
229→
230→ // Reset watchers at the start of each turn
231→ self.watchers.reset_turn();
232→ }
233→ }
234→ }
235→ }
236→
237→ /// London mulligan procedure.
238→ ///
239→ /// Each player simultaneously decides whether to mulligan. Players who
240→ /// mulligan shuffle their hand back and draw 7 again, then put N cards
241→ /// on the bottom of their library (where N = number of mulligans taken).
242→ fn london_mulligan(&mut self, player_ids: &[PlayerId]) {
243→ let max_mulligans = 6u32; // Can't mulligan below 1 card
244→
245→ // Track how many mulligans each player has taken
246→ let mut mulligan_count: HashMap = HashMap::new();
247→ let mut still_deciding: Vec = player_ids.to_vec();
248→
249→ for round in 0..max_mulligans {
250→ if still_deciding.is_empty() {
251→ break;
252→ }
253→
254→ let mut keeping = Vec::new();
255→ let mut mulliganing = Vec::new();
256→
257→ for &pid in &still_deciding {
258→ let hand: Vec = self
259→ .state
260→ .players
261→ .get(&pid)
262→ .map(|p| p.hand.iter().copied().collect())
263→ .unwrap_or_default();
264→
265→ let view = crate::decision::GameView::placeholder();
266→ let wants_mulligan = if let Some(dm) = self.decision_makers.get_mut(&pid) {
267→ dm.choose_mulligan(&view, &hand)
268→ } else {
269→ false
```
## Assistant
### Tool: Read
**Args:**
```json
{
"file_path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/game.rs",
"limit": 120,
"offset": 340
}
```
## Assistant
**Result** (success):
```
340→ }
341→
342→ /// Process the current step: turn-based actions, SBAs, triggers, priority.
343→ fn process_step(&mut self) {
344→ let step = self.state.current_step;
345→ let active = self.state.active_player;
346→
347→ // -- Turn-based actions --
348→ self.turn_based_actions(step, active);
349→
350→ // -- Check state-based actions (loop until stable) --
351→ self.process_state_based_actions();
352→
353→ // -- Handle triggered abilities --
354→ // TODO: Put triggered abilities on the stack (task #13)
355→
356→ // -- Priority loop --
357→ if has_priority(step) {
358→ self.priority_loop();
359→ }
360→ }
361→
362→ /// Execute turn-based actions for a step.
363→ fn turn_based_actions(&mut self, step: PhaseStep, active_player: PlayerId) {
364→ match step {
365→ PhaseStep::Untap => {
366→ // Untap all permanents controlled by the active player
367→ for perm in self.state.battlefield.iter_mut() {
368→ if perm.controller == active_player {
369→ perm.untap();
370→ perm.remove_summoning_sickness();
371→ }
372→ }
373→ // Empty mana pool (normally happens at end of each step, but
374→ // also at untap for clarity)
375→ if let Some(player) = self.state.players.get_mut(&active_player) {
376→ player.mana_pool.clear();
377→ }
378→ }
379→ PhaseStep::Draw => {
380→ // Active player draws a card
381→ // Skip draw on turn 1 for the starting player (two-player rule)
382→ if self.turn_manager.turn_number > 1 || self.state.turn_order[0] != active_player {
383→ self.draw_cards(active_player, 1);
384→ }
385→ }
386→ PhaseStep::Cleanup => {
387→ // Discard down to max hand size
388→ let discard_info = self
389→ .state
390→ .players
391→ .get(&active_player)
392→ .map(|p| {
393→ let count = p.discard_count();
394→ let hand: Vec = p.hand.iter().copied().collect();
395→ (count, hand)
396→ });
397→
398→ if let Some((discard_count, hand_cards)) = discard_info {
399→ if discard_count > 0 {
400→ let view = crate::decision::GameView::placeholder();
401→ let to_discard = if let Some(dm) =
402→ self.decision_makers.get_mut(&active_player)
403→ {
404→ dm.choose_discard(&view, &hand_cards, discard_count as usize)
405→ } else {
406→ hand_cards
407→ .iter()
408→ .rev()
409→ .take(discard_count as usize)
410→ .copied()
411→ .collect()
412→ };
413→ for card_id in to_discard {
414→ if let Some(player) =
415→ self.state.players.get_mut(&active_player)
416→ {
417→ player.hand.remove(card_id);
418→ }
419→ self.move_card_to_graveyard(card_id, active_player);
420→ }
421→ }
422→ }
423→ // Remove damage from all creatures and clear "until end of turn" effects
424→ for perm in self.state.battlefield.iter_mut() {
425→ if perm.is_creature() {
426→ perm.clear_damage();
427→ }
428→ // Clear granted keywords (from GainKeywordUntilEndOfTurn, Indestructible, Hexproof)
429→ perm.granted_keywords = crate::constants::KeywordAbilities::empty();
430→ perm.removed_keywords = crate::constants::KeywordAbilities::empty();
431→ // Remove "can't block" sentinel counters
432→ perm.counters.remove_all(&crate::counters::CounterType::Custom("cant_block".into()));
433→ // Revert temporary control changes (GainControlUntilEndOfTurn)
434→ if let Some(orig) = perm.original_controller.take() {
435→ perm.controller = orig;
436→ }
437→ }
438→ // Empty mana pools
439→ for player in self.state.players.values_mut() {
440→ player.mana_pool.clear();
441→ }
442→ }
443→ _ => {
444→ // Other steps: empty mana pool at step transition (simplified)
445→ // In full rules, mana empties at end of each step/phase.
446→ }
447→ }
448→ }
449→
450→ /// Run the priority loop: players take actions or pass until the stack
451→ /// resolves or the step ends.
452→ fn priority_loop(&mut self) {
453→ let active = self.state.active_player;
454→ let player_count = self.state.active_players().len() as u32;
455→ if player_count == 0 {
456→ return;
457→ }
458→
459→ let mut tracker = PriorityTracker::new(active, player_count);
```
## Assistant
## Assistant
### Tool: Grep
**Args:**
```json
{
"-C": 2,
"output_mode": "content",
"path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/game.rs",
"pattern": "advance_step|STEPS|phase_steps|TurnManager"
}
```
## Assistant
**Result** (success):
```
1-// Game — the top-level game runner.
2-//
3:// The Game struct ties together the GameState, TurnManager, and
4-// PlayerDecisionMaker implementations to run a complete game of Magic.
5-//
--
23-use crate::permanent::Permanent;
24-use crate::state::{GameState, StateBasedActions};
25:use crate::turn::{has_priority, PriorityTracker, TurnManager};
26-use crate::types::{AbilityId, ObjectId, PlayerId};
27-use crate::watchers::WatcherManager;
--
78- pub state: GameState,
79- /// The turn manager.
80: pub turn_manager: TurnManager,
81- /// Player decision-makers, keyed by PlayerId.
82- decision_makers: HashMap>,
--
137-
138- // Build turn manager
139: let turn_manager = TurnManager::new(player_ids.clone());
140-
141- // Build decision maker map
--
200-
201- // Advance to next step
202: match self.turn_manager.advance_step() {
203- Some(step) => {
204- // Empty mana pools at phase transitions
```
## Assistant
### Tool: Grep
**Args:**
```json
{
"-C": 5,
"output_mode": "content",
"path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/turn.rs",
"pattern": "fn advance_step|STEPS|const.*STEP"
}
```
## Assistant
**Result** (success):
```
14-use crate::types::PlayerId;
15-use serde::{Deserialize, Serialize};
16-use std::collections::VecDeque;
17-
18-/// The ordered list of steps in a normal turn.
19:pub const TURN_STEPS: &[PhaseStep] = &[
20- PhaseStep::Untap,
21- PhaseStep::Upkeep,
22- PhaseStep::Draw,
23- PhaseStep::PrecombatMain,
24- PhaseStep::BeginCombat,
--
61-
62-/// Manages turn state, tracking the current position in the turn sequence
63-/// and managing extra turns.
64-#[derive(Clone, Debug, Serialize, Deserialize)]
65-pub struct TurnManager {
66: /// The current step index into TURN_STEPS (0-12).
67- current_step_index: usize,
68-
69- /// Turn order (player IDs). This rotates as turns pass.
70- turn_order: Vec,
71-
--
112- }
113- }
114-
115- /// Get the current phase step.
116- pub fn current_step(&self) -> PhaseStep {
117: TURN_STEPS[self.current_step_index]
118- }
119-
120- /// Get the current turn phase.
121- pub fn current_phase(&self) -> TurnPhase {
122- step_to_phase(self.current_step())
--
128- }
129-
130- /// Advance to the next step. Returns the new step, or None if the turn is over.
131- ///
132- /// When the turn ends, the caller should call `next_turn()`.
133: pub fn advance_step(&mut self) -> Option {
134- loop {
135- self.current_step_index += 1;
136-
137: if self.current_step_index >= TURN_STEPS.len() {
138- // Turn is over
139- return None;
140- }
141-
142: let step = TURN_STEPS[self.current_step_index];
143-
144- // Skip first strike damage if no creature has first/double strike
145- if step == PhaseStep::FirstStrikeDamage && !self.has_first_strike {
146- continue;
147- }
```
## Assistant
### Tool: Read
**Args:**
```json
{
"file_path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/turn.rs",
"limit": 50,
"offset": 18
}
```
## Assistant
**Result** (success):
```
18→/// The ordered list of steps in a normal turn.
19→pub const TURN_STEPS: &[PhaseStep] = &[
20→ PhaseStep::Untap,
21→ PhaseStep::Upkeep,
22→ PhaseStep::Draw,
23→ PhaseStep::PrecombatMain,
24→ PhaseStep::BeginCombat,
25→ PhaseStep::DeclareAttackers,
26→ PhaseStep::DeclareBlockers,
27→ PhaseStep::FirstStrikeDamage,
28→ PhaseStep::CombatDamage,
29→ PhaseStep::EndCombat,
30→ PhaseStep::PostcombatMain,
31→ PhaseStep::EndStep,
32→ PhaseStep::Cleanup,
33→];
34→
35→/// Map a PhaseStep to its parent TurnPhase.
36→pub fn step_to_phase(step: PhaseStep) -> TurnPhase {
37→ match step {
38→ PhaseStep::Untap | PhaseStep::Upkeep | PhaseStep::Draw => TurnPhase::Beginning,
39→ PhaseStep::PrecombatMain => TurnPhase::PrecombatMain,
40→ PhaseStep::BeginCombat
41→ | PhaseStep::DeclareAttackers
42→ | PhaseStep::DeclareBlockers
43→ | PhaseStep::FirstStrikeDamage
44→ | PhaseStep::CombatDamage
45→ | PhaseStep::EndCombat => TurnPhase::Combat,
46→ PhaseStep::PostcombatMain => TurnPhase::PostcombatMain,
47→ PhaseStep::EndStep | PhaseStep::Cleanup => TurnPhase::Ending,
48→ }
49→}
50→
51→/// Steps where players normally receive priority.
52→/// No priority during Untap or Cleanup (unless triggers fire).
53→pub fn has_priority(step: PhaseStep) -> bool {
54→ !matches!(step, PhaseStep::Untap | PhaseStep::Cleanup)
55→}
56→
57→/// Steps where the active player can play spells at sorcery speed.
58→pub fn is_sorcery_speed(step: PhaseStep) -> bool {
59→ matches!(step, PhaseStep::PrecombatMain | PhaseStep::PostcombatMain)
60→}
61→
62→/// Manages turn state, tracking the current position in the turn sequence
63→/// and managing extra turns.
64→#[derive(Clone, Debug, Serialize, Deserialize)]
65→pub struct TurnManager {
66→ /// The current step index into TURN_STEPS (0-12).
67→ current_step_index: usize,
```
## Assistant
## Assistant
Good - the game **does** advance through all 13 steps, and the priority loop runs for all but Untap/Cleanup. But `turn_based_actions()` only has code for Untap, Draw, and Cleanup - combat damage is never dealt, attackers/blockers are never declared. Now I have the full picture. Let me write the updated ROADMAP.md.
## Assistant
### Tool: Write
**Args:**
```json
{
"content": "# Roadmap\n\nThis document describes implementation gaps between the Rust mtg-rl engine and the Java XMage reference engine, organized by impact on the 1,333 cards across our 4 sets (FDN, TLA, TDM, ECL).\n\n**Last audit: 2026-02-14** — Compared Rust engine (~14.6K lines, 21 source files) against Java XMage engine (full rules implementation).\n\n## Summary\n\n| Metric | Value |\n|--------|-------|\n| Cards registered | 1,333 (FDN 512, TLA 280, TDM 273, ECL 268) |\n| `Effect::Custom` fallbacks | 747 |\n| `StaticEffect::Custom` fallbacks | 160 |\n| `Cost::Custom` fallbacks | 33 |\n| **Total Custom fallbacks** | **940** |\n| Keywords defined | 47 |\n| Keywords mechanically enforced | 10 (but combat doesn't run, so only Haste + Defender active in practice) |\n| State-based actions | 7 of ~20 rules implemented |\n| Triggered abilities | Events emitted but abilities never put on stack |\n| Replacement effects | Data structures defined but not integrated |\n| Continuous effect layers | 7 layers defined but never applied |\n\n---\n\n## I. Critical Game Loop Gaps\n\nThese are structural deficiencies in `game.rs` that affect ALL cards, not just specific ones.\n\n### A. Combat Phase Not Connected\n\nThe `TurnManager` advances through all 13 steps (Untap → Upkeep → Draw → PrecombatMain → BeginCombat → DeclareAttackers → DeclareBlockers → FirstStrikeDamage → CombatDamage → EndCombat → PostcombatMain → EndStep → Cleanup) and the priority loop runs for all steps except Untap and Cleanup. **However**, `turn_based_actions()` only has code for 3 steps:\n\n| Step | Status | What's Missing |\n|------|--------|----------------|\n| Untap | **Implemented** | — |\n| Upkeep | No-op | Beginning-of-upkeep trigger emission |\n| Draw | **Implemented** | — |\n| PrecombatMain | Priority only | Works — spells/lands can be played |\n| BeginCombat | No-op | Begin-combat trigger emission |\n| DeclareAttackers | **No-op** | Must prompt active player to choose attackers, tap them, emit events |\n| DeclareBlockers | **No-op** | Must prompt defending player to choose blockers, emit events |\n| FirstStrikeDamage | **No-op** | Must deal first/double strike damage |\n| CombatDamage | **No-op** | Must deal regular combat damage, apply trample/deathtouch/lifelink |\n| EndCombat | No-op | Remove-from-combat cleanup |\n| PostcombatMain | Priority only | Works — spells/lands can be played |\n| EndStep | No-op | End-step trigger emission |\n| Cleanup | **Implemented** | — |\n\n`combat.rs` has fully implemented functions for `can_attack()`, `can_block()`, combat damage assignment (with first strike, double strike, trample, deathtouch, menace), but **none of these are ever called** from the game loop.\n\n**Impact:** Every creature card in all 4 sets is affected. Combat is the primary way to win games. Without it, the engine runs in a \"goldfish\" mode where no combat damage is ever dealt.\n\n**Fix:** Wire `combat.rs` into `turn_based_actions()` for DeclareAttackers, DeclareBlockers, FirstStrikeDamage, and CombatDamage. Add `choose_attackers()` and `choose_blockers()` to `PlayerDecisionMaker` trait.\n\n### B. Triggered Abilities Not Stacked\n\nEvents are emitted (`GameEvent` structs) and the `AbilityStore` tracks which triggered abilities respond to which `EventType`s, but triggered abilities are **never put on the stack**. There is a TODO comment in `process_step()`:\n\n```rust\n// -- Handle triggered abilities --\n// TODO: Put triggered abilities on the stack (task #13)\n```\n\nIn Java XMage, after each game action, all pending triggers are gathered and placed on the stack in APNAP order (active player's triggers first, then next player). Each trigger gets its own stack entry and can be responded to.\n\n**Impact:** Every card with a triggered ability (ETB triggers, attack triggers, death triggers, upkeep triggers, damage triggers) silently does nothing beyond its initial cast. This affects **hundreds** of cards across all sets.\n\n**Fix:** After each state-based action loop, scan `AbilityStore` for triggered abilities whose trigger conditions are met by recent events. Push each onto the stack as a `StackItem`. Resolve via the existing priority loop.\n\n### C. Continuous Effect Layers Not Applied\n\nThe `effects.rs` file defines a full 7-layer system matching MTG rules 613:\n\n1. Copy → 2. Control → 3. Text → 4. Type → 5. Color → 6. Ability → 7. P/T (with sub-layers for CDA, Set, Modify, Counters, Switch)\n\n`ContinuousEffect`, `EffectModification`, and `Layer`/`SubLayer` enums are all defined. But the game loop **never recalculates characteristics** using these layers. P/T boosts from lords, keyword grants, type changes — none of these are applied.\n\nIn Java XMage, `ContinuousEffects.apply()` runs after every game action, recalculating all permanent characteristics in layer order. This is what makes lord effects, anthem effects, and ability-granting cards work.\n\n**Impact:** All cards with `StaticEffect::Boost`, `StaticEffect::GrantKeyword`, and other continuous effects are non-functional. ~50+ lord/anthem cards across all sets.\n\n**Fix:** Add a `apply_continuous_effects()` method to `Game` that iterates battlefield permanents' `static_effects` and applies them in layer order. Call it after every state-based action check.\n\n### D. Replacement Effects Not Integrated\n\n`ReplacementEffect` and `ReplacementKind` are defined in `effects.rs` with variants like `Prevent`, `ExileInstead`, `ModifyAmount`, `RedirectTarget`, `EnterTapped`, `EnterWithCounters`, `Custom`. But there is **no event interception** in the game loop — events happen without checking for replacements first.\n\nIn Java XMage, replacement effects are checked via `getReplacementEffects()` before every event. Each replacement's `applies()` is checked, and `replaceEvent()` modifies or cancels the event.\n\n**Impact:** Damage prevention, death replacement (\"exile instead of dying\"), Doubling Season, \"enters tapped\" enforcement, and similar effects don't work. Affects ~30+ cards.\n\n**Fix:** Before each event emission, check registered replacement effects. If any apply, call `replaceEvent()` and use the modified event instead.\n\n---\n\n## II. Keyword Enforcement\n\n47 keywords are defined as bitflags in `KeywordAbilities`. Most are decorative.\n\n### Mechanically Enforced (10 keywords — in combat.rs, but combat doesn't run)\n\n| Keyword | Where | How |\n|---------|-------|-----|\n| FLYING | `combat.rs:205` | Flyers can only be blocked by flying/reach |\n| REACH | `combat.rs:205` | Can block flyers |\n| DEFENDER | `permanent.rs:249` | Cannot attack |\n| HASTE | `permanent.rs:250` | Bypasses summoning sickness |\n| FIRST_STRIKE | `combat.rs:241-248` | Damage in first-strike step |\n| DOUBLE_STRIKE | `combat.rs:241-248` | Damage in both steps |\n| TRAMPLE | `combat.rs:296-298` | Excess damage to defending player |\n| DEATHTOUCH | `combat.rs:280-286` | 1 damage = lethal |\n| MENACE | `combat.rs:216-224` | Must be blocked by 2+ creatures |\n| INDESTRUCTIBLE | `state.rs:296` | Survives lethal damage (SBA) |\n\nOf these, only **Haste** and **Defender** are active in practice (checked during the priority loop for can_attack). The other 8 are only checked in combat.rs functions that are never called.\n\n### Not Enforced (37 keywords)\n\n| Keyword | Java Behavior | Rust Status |\n|---------|--------------|-------------|\n| VIGILANCE | Attacking doesn't cause tap | Not checked |\n| LIFELINK | Damage → life gain | Not connected |\n| FLASH | Cast at instant speed | Partially (blocks sorcery-speed only) |\n| HEXPROOF | Can't be targeted by opponents | Not checked during targeting |\n| SHROUD | Can't be targeted at all | Not checked |\n| PROTECTION | Prevents damage/targeting/blocking/enchanting | Not checked |\n| WARD | Counter unless cost paid | Stored as StaticEffect, not enforced |\n| FEAR | Only blocked by black/artifact | Not checked |\n| INTIMIDATE | Only blocked by same color/artifact | Not checked |\n| SHADOW | Only blocked by/blocks shadow | Not checked |\n| PROWESS | +1/+1 when noncreature spell cast | Trigger never fires |\n| UNDYING | Return with +1/+1 counter on death | No death replacement |\n| PERSIST | Return with -1/-1 counter on death | No death replacement |\n| WITHER | Damage as -1/-1 counters | Not checked |\n| INFECT | Damage as -1/-1 counters + poison | Not checked |\n| TOXIC | Combat damage → poison counters | Not checked |\n| UNBLOCKABLE | Can't be blocked | Not checked |\n| CHANGELING | All creature types | Not checked in type queries |\n| CASCADE | Exile-and-cast on cast | No trigger |\n| CONVOKE | Tap creatures to pay | Not checked in cost payment |\n| DELVE | Exile graveyard to pay | Not checked in cost payment |\n| EVOLVE | +1/+1 counter on bigger ETB | No trigger |\n| EXALTED | +1/+1 when attacking alone | No trigger |\n| EXPLOIT | Sacrifice creature on ETB | No trigger |\n| FLANKING | Blockers get -1/-1 | Not checked |\n| FORESTWALK | Unblockable vs forest controller | Not checked |\n| ISLANDWALK | Unblockable vs island controller | Not checked |\n| MOUNTAINWALK | Unblockable vs mountain controller | Not checked |\n| PLAINSWALK | Unblockable vs plains controller | Not checked |\n| SWAMPWALK | Unblockable vs swamp controller | Not checked |\n| TOTEM_ARMOR | Prevents enchanted creature death | No replacement |\n| AFFLICT | Life loss when blocked | No trigger |\n| BATTLE_CRY | +1/+0 to other attackers | No trigger |\n| SKULK | Can't be blocked by greater power | Not checked |\n| FABRICATE | Counters or tokens on ETB | No choice/trigger |\n| STORM | Copy for each prior spell | No trigger |\n| PARTNER | Commander pairing | Not relevant |\n\n---\n\n## III. State-Based Actions\n\nChecked in `state.rs:check_state_based_actions()`:\n\n| Rule | Description | Status |\n|------|-------------|--------|\n| 704.5a | Player at 0 or less life loses | **Implemented** |\n| 704.5b | Player draws from empty library loses | **Not implemented** |\n| 704.5c | 10+ poison counters = loss | **Implemented** |\n| 704.5d | Token not on battlefield ceases to exist | **Not implemented** |\n| 704.5e | 0-cost copy on stack/BF ceases to exist | **Not implemented** |\n| 704.5f | Creature with 0 toughness → graveyard | **Implemented** |\n| 704.5g | Lethal damage → destroy (if not indestructible) | **Implemented** |\n| 704.5i | Planeswalker with 0 loyalty → graveyard | **Implemented** |\n| 704.5j | Legend rule (same name) | **Implemented** |\n| 704.5n | Aura not attached → graveyard | **Not implemented** |\n| 704.5p | Equipment/Fortification illegal attach → unattach | **Not implemented** |\n| 704.5r | +1/+1 and -1/-1 counter annihilation | **Implemented** |\n| 704.5s | Saga with lore counters ≥ chapters → sacrifice | **Not implemented** |\n\n**Missing SBAs:** Library-empty loss, token cleanup, aura fall-off, equipment detach, saga sacrifice. These affect ~40+ cards.\n\n---\n\n## IV. Missing Engine Systems\n\nThese require new engine architecture beyond adding match arms to existing functions.\n\n### Tier 1: Foundational (affect 100+ cards each)\n\n#### 1. Combat Integration\n- Wire `combat.rs` functions into `turn_based_actions()` for DeclareAttackers, DeclareBlockers, CombatDamage\n- Add `choose_attackers()` / `choose_blockers()` to `PlayerDecisionMaker`\n- Connect lifelink (damage → life gain), vigilance (no tap), and other combat keywords\n- **Cards affected:** Every creature in all 4 sets (~800+ cards)\n- **Java reference:** `GameImpl.combat`, `Combat.java`, `CombatGroup.java`\n\n#### 2. Triggered Ability Stacking\n- After each game action, scan for triggered abilities whose conditions match recent events\n- Push triggers onto stack in APNAP order\n- Resolve via existing priority loop\n- **Cards affected:** Every card with ETB, attack, death, damage, upkeep, or endstep triggers (~400+ cards)\n- **Java reference:** `GameImpl.checkStateAndTriggered()`, 84+ `Watcher` classes\n\n#### 3. Continuous Effect Layer Application\n- Recalculate permanent characteristics after each game action\n- Apply StaticEffect variants (Boost, GrantKeyword, CantAttack, CantBlock, etc.) in layer order\n- Duration tracking (while-on-battlefield, until-end-of-turn, etc.)\n- **Cards affected:** All lord/anthem effects, keyword-granting permanents (~50+ cards)\n- **Java reference:** `ContinuousEffects.java`, 7-layer system\n\n### Tier 2: Key Mechanics (affect 10-30 cards each)\n\n#### 4. Equipment System\n- Attach/detach mechanic (Equipment attaches to creature you control)\n- Equip cost (activated ability, sorcery speed)\n- Stat/keyword bonuses applied while attached (via continuous effects layer)\n- Detach when creature leaves battlefield (SBA)\n- **Blocked cards:** Basilisk Collar, Swiftfoot Boots, Goldvein Pick, Fishing Pole, all Equipment (~15+ cards)\n- **Java reference:** `EquipAbility.java`, `AttachEffect.java`\n\n#### 5. Aura/Enchant System\n- Auras target on cast, attach on ETB\n- Apply continuous effects while attached (P/T boosts, keyword grants, restrictions)\n- Fall off when enchanted permanent leaves (SBA)\n- Enchant validation (enchant creature, enchant permanent, etc.)\n- **Blocked cards:** Pacifism, Obsessive Pursuit, Eaten by Piranhas, Angelic Destiny (~15+ cards)\n- **Java reference:** `AuraReplacementEffect.java`, `AttachEffect.java`\n\n#### 6. Replacement Effect Pipeline\n- Before each event, check registered replacement effects\n- `applies()` filter + `replaceEvent()` modification\n- Support common patterns: exile-instead-of-die, enters-tapped, enters-with-counters, damage prevention\n- Prevent infinite loops (each replacement applies once per event)\n- **Blocked features:** Damage prevention, death replacement, Doubling Season, Undying, Persist (~30+ cards)\n- **Java reference:** `ReplacementEffectImpl.java`, `ContinuousEffects.getReplacementEffects()`\n\n#### 7. X-Cost Spells\n- Announce X before paying mana (X ≥ 0)\n- Track X value on the stack; pass to effects on resolution\n- Support {X}{X}, min/max X, X in activated abilities\n- Add `choose_x_value()` to `PlayerDecisionMaker`\n- **Blocked cards:** Day of Black Sun, Genesis Wave, Finale of Revelation, Spectral Denial (~10+ cards)\n- **Java reference:** `VariableManaCost.java`, `ManaCostsImpl.getX()`\n\n#### 8. Impulse Draw (Exile-and-Play)\n- \"Exile top card, you may play it until end of [next] turn\"\n- Track exiled-but-playable cards in game state with expiration\n- Allow casting from exile via `AsThoughEffect` equivalent\n- **Blocked cards:** Equilibrium Adept, Kulrath Zealot, Sizzling Changeling, Burning Curiosity, Etali (~10+ cards)\n- **Java reference:** `PlayFromNotOwnHandZoneTargetEffect.java`\n\n#### 9. Graveyard Casting (Flashback/Escape)\n- Cast from graveyard with alternative cost\n- Exile after resolution (flashback) or with escaped counters\n- Requires `AsThoughEffect` equivalent to allow casting from non-hand zones\n- **Blocked cards:** Cards with \"Cast from graveyard, then exile\" text (~6+ cards)\n- **Java reference:** `FlashbackAbility.java`, `PlayFromNotOwnHandZoneTargetEffect.java`\n\n#### 10. Planeswalker System\n- Loyalty counters as activation resource\n- Loyalty abilities: `PayLoyaltyCost(amount)` — add or remove loyalty counters\n- One loyalty ability per turn, sorcery speed\n- Can be attacked (defender selection during declare attackers)\n- Damage redirected from player to planeswalker (or direct attack)\n- SBA: 0 loyalty → graveyard (already implemented)\n- **Blocked cards:** Ajani, Chandra, Kaito, Liliana, Vivien, all planeswalkers (~10+ cards)\n- **Java reference:** `LoyaltyAbility.java`, `PayLoyaltyCost.java`\n\n### Tier 3: Advanced Systems (affect 5-10 cards each)\n\n#### 11. Spell/Permanent Copy\n- Copy spell on stack with same abilities; optionally choose new targets\n- Copy permanent on battlefield (token with copied attributes via Layer 1)\n- Copy + modification (e.g., \"except it's a 1/1\")\n- **Blocked cards:** Electroduplicate, Rite of Replication, Self-Reflection, Flamehold Grappler (~8+ cards)\n- **Java reference:** `CopyEffect.java`, `CreateTokenCopyTargetEffect.java`\n\n#### 12. Delayed Triggers\n- \"When this creature dies this turn, draw a card\" — one-shot trigger registered for remainder of turn\n- Framework: register trigger with expiration, fire when condition met, remove after\n- **Blocked cards:** Undying Malice, Fake Your Own Death, Desperate Measures, Scarblades Malice (~5+ cards)\n- **Java reference:** `DelayedTriggeredAbility.java`\n\n#### 13. Saga Enchantments\n- Lore counters added on ETB and after draw step\n- Chapter abilities trigger when lore counter matches chapter number\n- Sacrifice after final chapter (SBA)\n- **Blocked cards:** 6+ Saga cards in TDM/TLA\n- **Java reference:** `SagaAbility.java`\n\n#### 14. Additional Combat Phases\n- \"Untap all creatures, there is an additional combat phase\"\n- Insert extra combat steps into the turn sequence\n- **Blocked cards:** Aurelia the Warleader, All-Out Assault (~3 cards)\n\n#### 15. Conditional Cost Modifications\n- `CostReduction` stored but not applied during cost calculation\n- \"Second spell costs {1} less\", Affinity, Convoke, Delve\n- Need cost-modification pass before mana payment\n- **Blocked cards:** Highspire Bell-Ringer, Allies at Last, Ghalta Primal Hunger (~5+ cards)\n- **Java reference:** `CostModificationEffect.java`, `SpellAbility.adjustCosts()`\n\n### Tier 4: Set-Specific Mechanics\n\n#### 16. Earthbend (TLA)\n- \"Look at top N, put a land to hand, rest on bottom\"\n- Similar to Explore/Impulse — top-of-library selection\n- **Blocked cards:** Badgermole, Badgermole Cub, Ostrich-Horse, Dai Li Agents, many TLA cards (~20+ cards)\n\n#### 17. Behold (ECL)\n- Reveal-and-exile-from-hand as alternative cost or condition\n- Track \"beheld\" state for triggered abilities\n- **Blocked cards:** Champion of the Weird, Champions of the Perfect, Molten Exhale, Osseous Exhale (~15+ cards)\n\n#### 18. ~~Vivid (ECL)~~ (DONE)\nColor-count calculation implemented. 6 Vivid effect variants added. 6 cards fixed.\n\n#### 19. Renew (TDM)\n- Counter-based death replacement (exile with counters, return later)\n- Requires replacement effect pipeline (Tier 2, item 6)\n- **Blocked cards:** ~5+ TDM cards\n\n#### 20. Endure (TDM)\n- Put +1/+1 counters; if would die, exile with counters instead\n- Requires replacement effect pipeline\n- **Blocked cards:** ~3+ TDM cards\n\n---\n\n## V. Effect System Gaps\n\n### Implemented Effect Variants (~55 of 62)\n\nThe following Effect variants have working `execute_effects()` match arms:\n\n**Damage:** DealDamage, DealDamageAll, DealDamageOpponents, DealDamageVivid\n**Life:** GainLife, GainLifeVivid, LoseLife, LoseLifeOpponents, LoseLifeOpponentsVivid, SetLife\n**Removal:** Destroy, DestroyAll, Exile, Sacrifice, PutOnLibrary\n**Card Movement:** Bounce, ReturnFromGraveyard, Reanimate, DrawCards, DrawCardsVivid, DiscardCards, DiscardOpponents, Mill, SearchLibrary, LookTopAndPick\n**Counters:** AddCounters, AddCountersSelf, AddCountersAll, RemoveCounters\n**Tokens:** CreateToken, CreateTokenTappedAttacking, CreateTokenVivid\n**Combat:** CantBlock, Fight, Bite, MustBlock\n**Stats:** BoostUntilEndOfTurn, BoostPermanent, BoostAllUntilEndOfTurn, BoostUntilEotVivid, BoostAllUntilEotVivid, SetPowerToughness\n**Keywords:** GainKeywordUntilEndOfTurn, GainKeyword, LoseKeyword, GrantKeywordAllUntilEndOfTurn, Indestructible, Hexproof\n**Control:** GainControl, GainControlUntilEndOfTurn\n**Utility:** TapTarget, UntapTarget, CounterSpell, Scry, AddMana, Modal, DoIfCostPaid, ChooseCreatureType, ChooseTypeAndDrawPerPermanent\n\n### Unimplemented Effect Variants\n\n| Variant | Description | Cards Blocked |\n|---------|-------------|---------------|\n| `GainProtection` | Target gains protection from quality | ~5 |\n| `PreventCombatDamage` | Fog / damage prevention | ~5 |\n| `Custom(String)` | Catch-all for untyped effects | 747 instances |\n\n### Custom Effect Fallback Analysis (747 Effect::Custom)\n\nThese are effects where no typed variant exists. Grouped by what engine feature would replace them:\n\n| Category | Count | Sets | Engine Feature Needed |\n|----------|-------|------|----------------------|\n| Generic ETB stubs (\"ETB effect.\") | 79 | All | Triggered ability stacking |\n| Generic activated ability stubs (\"Activated effect.\") | 67 | All | Proper cost+effect binding on abilities |\n| Attack/combat triggers | 45 | All | Combat integration + triggered abilities |\n| Cast/spell triggers | 47 | All | Triggered abilities + cost modification |\n| Aura/equipment attachment | 28 | FDN,TDM,ECL | Equipment/Aura system |\n| Exile-and-play effects | 25 | All | Impulse draw |\n| Generic spell stubs (\"Spell effect.\") | 21 | All | Per-card typing with existing variants |\n| Dies/sacrifice triggers | 18 | FDN,TLA | Triggered abilities |\n| Conditional complex effects | 30+ | All | Per-card analysis; many are unique |\n| Tapped/untap mechanics | 10 | FDN,TLA | Minor — mostly per-card fixes |\n| Saga mechanics | 6 | TDM,TLA | Saga system |\n| Earthbend keyword | 5 | TLA | Earthbend mechanic |\n| Copy/clone effects | 8+ | TDM,ECL | Spell/permanent copy |\n| Cost modifiers | 4 | FDN,ECL | Cost modification system |\n| X-cost effects | 5+ | All | X-cost system |\n\n### StaticEffect::Custom Analysis (160 instances)\n\n| Category | Count | Engine Feature Needed |\n|----------|-------|-----------------------|\n| Generic placeholder (\"Static effect.\") | 90 | Per-card analysis; diverse |\n| Conditional continuous (\"Conditional continuous effect.\") | 4 | Layer system + conditions |\n| Dynamic P/T (\"P/T = X\", \"+X/+X where X = ...\") | 11 | Characteristic-defining abilities (Layer 7a) |\n| Evasion/block restrictions | 5 | Restriction effects in combat |\n| Protection effects | 4 | Protection keyword enforcement |\n| Counter/spell protection (\"Can't be countered\") | 8 | Uncounterable flag or replacement effect |\n| Keyword grants (conditional) | 4 | Layer 6 + conditions |\n| Damage modification | 4 | Replacement effects |\n| Transform/copy | 3 | Copy layer + transform |\n| Mana/land effects | 3 | Mana ability modification |\n| Cost reduction | 2 | Cost modification system |\n| Keyword abilities (Kicker, Convoke, Delve) | 4 | Alternative/additional costs |\n| Token doubling | 1 | Replacement effect |\n| Trigger multiplier | 1 | Triggered ability system |\n| Other unique effects | 16 | Per-card analysis |\n\n### Cost::Custom Analysis (33 instances)\n\n| Category | Count | Engine Feature Needed |\n|----------|-------|-----------------------|\n| Complex mana+tap activated abilities | 13 | Better activated ability cost parsing |\n| Sacrifice-based activated abilities | 9 | Sacrifice-other as part of compound costs |\n| Tap-creature costs (convoke-like) | 5 | Tap-other-creature cost variant |\n| Exile costs (self, enchantment, graveyard) | 3 | Exile-self / exile-zone cost variants |\n| Complex multi-part costs | 2 | Compound cost support |\n| Discard hand | 1 | Discard-hand cost variant |\n\n---\n\n## VI. Per-Set Custom Fallback Counts\n\n| Set | Effect::Custom | StaticEffect::Custom | Cost::Custom | Total |\n|-----|---------------|---------------------|-------------|-------|\n| FDN (Foundations) | 322 | 58 | 21 | 401 |\n| TLA (Avatar: TLA) | 197 | 54 | 2 | 253 |\n| TDM (Tarkir: Dragonstorm) | 111 | 16 | 3 | 130 |\n| ECL (Lorwyn Eclipsed) | 117 | 32 | 7 | 156 |\n| **Total** | **747** | **160** | **33** | **940** |\n\nDetailed per-card breakdowns in `docs/{fdn,tla,tdm,ecl}-remediation.md`.\n\n---\n\n## VII. Comparison with Java XMage\n\nFeatures the Java engine has that the Rust engine lacks entirely:\n\n| Java Feature | Java Location | Rust Status |\n|-------------|--------------|-------------|\n| **84+ Watcher classes** | `mage.watchers.common/` | Basic `WatcherManager` only |\n| **Replacement effect pipeline** | `ContinuousEffects.getReplacementEffects()` | Structs defined, not integrated |\n| **7-layer continuous effect application** | `ContinuousEffects.apply()` | Layers defined, never applied |\n| **RequirementEffect** (must attack/block) | `mage.abilities.effects.RequirementEffect` | No equivalent |\n| **RestrictionEffect** (can't attack/block) | `mage.abilities.effects.RestrictionEffect` | Partial (CantAttack/CantBlock as data) |\n| **AsThoughEffect** (play from other zones) | `mage.abilities.effects.AsThoughEffect` | No equivalent |\n| **CostModificationEffect** | `mage.abilities.effects.CostModificationEffect` | CostReduction stored but not applied |\n| **PreventionEffect** (damage prevention) | `mage.abilities.effects.PreventionEffect` | No equivalent |\n| **Equipment attachment** | `EquipAbility`, `AttachEffect` | No equivalent |\n| **Aura attachment** | `AuraReplacementEffect` | No equivalent |\n| **Planeswalker loyalty abilities** | `LoyaltyAbility`, `PayLoyaltyCost` | No equivalent |\n| **X-cost system** | `VariableManaCost`, `ManaCostsImpl.getX()` | No equivalent |\n| **Spell copying** | `CopyEffect`, `CopySpellForEachItCouldTargetEffect` | No equivalent |\n| **Delayed triggered abilities** | `DelayedTriggeredAbility` | No equivalent |\n| **Alternative costs** (Flashback, Evoke, etc.) | `AlternativeCostSourceAbility` | Evoke stored as StaticEffect, not enforced |\n| **Additional costs** (Kicker, Buyback, etc.) | `OptionalAdditionalCostImpl` | No equivalent |\n| **Combat damage assignment order** | `CombatGroup.pickBlockerOrder()` | Simplified (first blocker takes all) |\n| **Spell target legality check on resolution** | `Spell.checkTargets()` | Targets checked at cast, not re-validated |\n| **Mana restriction** (\"spend only on creatures\") | `ManaPool.conditionalMana` | Not tracked |\n| **Hybrid mana** ({B/R}, {2/G}) | `HybridManaCost` | Not modeled |\n| **Zone change tracking** (LKI) | `getLKIBattlefield()` | No last-known-information |\n\n---\n\n## VIII. Phased Implementation Plan\n\nPriority ordered by cards-unblocked per effort.\n\n### Phase 1: Make the Engine Functional (combat + triggers)\n\n1. **Combat integration** — Wire `combat.rs` into `turn_based_actions()`. Add `choose_attackers()` / `choose_blockers()` to decision maker. Connect lifelink, vigilance. This single change makes every creature card functional and enables the game to have winners/losers through combat. **~800+ cards affected.**\n\n2. **Triggered ability stacking** — After each game action, scan for triggered abilities, push onto stack in APNAP order. This makes ETB abilities, attack triggers, death triggers, upkeep triggers, and damage triggers all work. **~400+ cards affected.**\n\n3. **Continuous effect layer application** — Recalculate permanent characteristics (P/T, keywords, types) by applying StaticEffect variants in layer order. Makes lord/anthem effects functional. **~50+ cards affected.**\n\n### Phase 2: Core Missing Mechanics\n\n4. **Replacement effect pipeline** — Event interception. Enables damage prevention, death replacement, enters-tapped enforcement, Undying/Persist. **~30+ cards.**\n\n5. **Equipment system** — Attach/detach, equip cost, stat application. **~15+ cards.**\n\n6. **Aura/enchant system** — Attach on ETB, apply continuous effects while attached, fall-off SBA. **~15+ cards.**\n\n7. **X-cost spells** — Announce X, track on stack, pass to effects. **~10+ cards.**\n\n8. **Impulse draw** — Exile-and-play tracking with expiration. **~10+ cards.**\n\n### Phase 3: Advanced Systems\n\n9. **Planeswalker system** — Loyalty abilities, can-be-attacked, damage redirection. **~10+ cards.**\n\n10. **Spell/permanent copy** — Clone spells on stack, create token copies. **~8+ cards.**\n\n11. **Delayed triggers** — One-shot triggered abilities with expiration. **~5+ cards.**\n\n12. **Graveyard casting** — Flashback, Escape, cast-from-graveyard. **~6+ cards.**\n\n13. **Saga enchantments** — Lore counters, chapter abilities. **~6+ cards.**\n\n14. **Cost modification** — Apply CostReduction during cost calculation. **~5+ cards.**\n\n15. **Additional combat phases** — Extra attack steps. **~3 cards.**\n\n### Phase 4: Set-Specific Mechanics\n\n16. **Earthbend** (TLA) — Top-N selection, land to hand. **~20+ cards.**\n\n17. **Behold** (ECL) — Reveal-from-hand alternative cost. **~15+ cards.**\n\n18. **Renew/Endure** (TDM) — Counter-based death replacement (needs replacement pipeline). **~8+ cards.**\n\n19. ~~**Vivid** (ECL)~~ — **DONE.** Color-count calculation + 6 effect variants.\n\n20. ~~**Modal spells**~~ — **DONE.** `Effect::Modal` + `choose_mode()`.\n\n21. ~~**Fight/Bite**~~ — **DONE.** `Effect::Fight` + `Effect::Bite` with dual targeting.\n\n22. ~~**Token stat parsing**~~ — **DONE.** `CreateToken` parses P/T and keywords from name string.\n\n### Phase 5: Eliminate Custom Fallbacks\n\nAfter the above systems are in place, systematically replace remaining `Custom(String)` fallbacks with typed variants:\n\n- **Easy wins (~100 cards):** Generic stubs (\"ETB effect\", \"Activated effect\", \"Spell effect\") where the effect is a simple combination of existing typed variants\n- **Medium (~200 cards):** Cards needing one of the systems above (triggers, layers, combat) plus per-card typing\n- **Hard (~50+ cards):** Cards with truly unique mechanics needing new Effect variants\n\n---\n\n## IX. Previously Completed Work\n\n**Batch 1-10 remediation** (2026-02-13 to 2026-02-14): Fixed ~60 cards by replacing Custom effects with typed variants. Added engine features: source-fallback for counters, Ward variant, EntersTappedUnless variant, mass-buff effects (BoostAllUntilEndOfTurn, GrantKeywordAllUntilEndOfTurn), AddCountersAll, AddCountersSelf, 7 cost implementations (RemoveCounters, Blight, ExileFromGraveyard, ExileFromHand, SacrificeOther, UntapSelf, Custom), Vivid mechanic (6 effect variants + color counting), Modal spells (Effect::Modal + ModalMode), Fight/Bite mechanics.\n\nSee `docs/work-queue.md` for the batch-fix loop and per-set remediation docs for card-level details.\n",
"file_path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/ROADMAP.md"
}
```
## Assistant
**Result** (success):
```
The file /mnt/dest-btrfs/home/jc/src/mage/mtg-rl/ROADMAP.md has been overwritten successfully.
```
## Assistant
The ROADMAP.md has been rewritten. Here's a summary of the key findings from comparing the two engines:
**Critical gaps (affect ALL cards):**
1. **Combat not wired in** — `combat.rs` has full damage/blocking logic but `turn_based_actions()` only handles Untap/Draw/Cleanup. Every creature is affected (~800+ cards).
2. **Triggered abilities never stack** — Events are emitted but abilities don't fire. ETB, attack, death, upkeep triggers are all silent (~400+ cards).
3. **Continuous effect layers never applied** — 7-layer system defined but never runs. Lord effects, anthems, keyword grants are all decorative (~50+ cards).
4. **Replacement effects not integrated** — Structs exist but no event interception. Damage prevention, death replacement, enters-tapped don't work (~30+ cards).
**Keyword enforcement:** 10 of 47 keywords have mechanical code in combat.rs, but since combat doesn't run, only Haste and Defender are active in practice. Lifelink, Vigilance, Hexproof, Protection, and 35 others are purely decorative.
**940 Custom fallbacks** across the 4 sets (FDN: 401, TLA: 253, ECL: 156, TDM: 130) — the largest categories being generic ETB/activated/spell stubs that need triggered ability stacking to work.
**Java-exclusive systems** the Rust engine completely lacks: 84+ watcher classes, equipment/aura attachment, planeswalker loyalty abilities, X-cost spells, spell copying, delayed triggers, alternative/additional costs, AsThoughEffect, combat damage assignment order, hybrid mana, and last-known-information tracking.
## User
a2b068c
completed
Agent "Explore Java engine capabilities" completed
Perfect! I now have a comprehensive understanding. Let me create a final summary document:
Based on my thorough exploration of the Java XMage engine, here's a comprehensive catalog of the key capabilities you need to understand for identifying gaps in the Rust reimplementation:
## XMage Java Engine Core Architecture
### 1. GAME LOOP & TURN STRUCTURE
- **Main loop**: `GameImpl.play()` → outer loop over turns, calls `playTurn()` for each player
- **Turn execution**: `Turn.play()` executes phases in sequence (Untap, Upkeep, Draw, Pre-Combat Main, Combat, Post-Combat Main, End)
- **Priority system**: `GameImpl.playPriority()` handles stack resolution and player interactions
- Players receive priority sequentially, pass when no actions available
- When all players pass with stack empty → game proceeds to next phase
- When all players pass with stack non-empty → resolve top stack object
- **Turn structure events**: Full event coverage (UNTAP_STEP, UPKEEP_STEP, DRAW_STEP, PRECOMBAT_MAIN_PHASE, COMBAT_PHASE, POSTCOMBAT_MAIN_PHASE, END_PHASE, CLEANUP_STEP) with PRE, POST variants
- **Extra turns**: `playExtraTurns()` manages turn mods/extra turns before normal turn progression
### 2. EFFECT SYSTEM - COMPREHENSIVE HIERARCHY
**Three main effect categories:**
1. **OneShotEffect** - One-time effects that resolve immediately
- `apply()` method executes effect once
- Examples: DealDamageTargetEffect, DestroyTargetEffect, DrawCardsEqualsEffect
2. **ContinuousEffect** - Ongoing effects that apply in layers (616.1-7)
- Applied across 7 layers: Copy → Control → Text → Type → Color → Ability → P/T
- Duration-based (EOT, EOCombat, until end of turn, permanent)
- Examples: BoostSourceEffect, GrantAbilitySourceEffect, BecomesFaceDownCreatureEffect
3. **ReplacementEffect** - Intercepts events before they happen
- `replaceEvent()` modifies or prevents events
- `applies()` checks if this replacement should apply
- Examples: AuraReplacementEffect (aura attachment validation), CopyEffect (copy replacements)
**Additional effect types:**
- **PreventionEffect** - Damage prevention ("prevent up to X damage")
- **RequirementEffect** - Forces creatures to attack/block
- **RestrictionEffect** - Prevents actions (can't attack, can't block)
- **CostModificationEffect** - Changes spell/ability costs
- **ContinuousRuleModifyingEffect** - Rules changes (e.g., "flying is unblockable")
- **AsThoughEffect** - "As though" effects (play without casting, block with flying, etc.)
**The effect manager `ContinuousEffects` maintains:**
- `layeredEffects` - applied in 7 layers per Layer enum
- `replacementEffects` - checked first on events
- `preventionEffects` - damage prevention
- `requirementEffects` - attack/block requirements
- `restrictionEffects` - can't attack/block/cast restrictions
### 3. CONTINUOUS EFFECTS & THE 7-LAYER SYSTEM
**Layer execution order (608.2):**
1. **Copy** (Layer.CopyEffects_1) - Copy effects determine what a permanent looks like
2. **Control** (Layer.ControlChangingEffects_2) - Control-changing effects
3. **Text** (Layer.TextChangingEffects_3) - Text-modifying effects
4. **Type** (Layer.TypeChangingEffects_4) - Type/subtype-changing effects
5. **Color** (Layer.ColorChangingEffects_5) - Color-changing effects
6. **Ability** (Layer.AbilityAddingRemovingEffects_6) - Grant/remove abilities
7. **P/T** (Layer.PTChangingEffects_7) - Power/toughness changes
- **Player Effects** - Affects players (life total, max hand size, etc.)
- **Rules Effects** - State-based actions, triggered ability checking
**ContinuousEffect interface requires:**
- `apply(Layer, SubLayer, Ability source, Game game)` - apply effect in specific layer
- `hasLayer(Layer)` - declare which layers this effect uses
- `isInactive(source, game)` - check if effect should stop applying
- Duration management (Duration enum: WHILE_ON_BATTLEFIELD, UNTIL_END_OF_TURN, EOCombat, etc.)
### 4. COMBAT SYSTEM
**Combat state management** (`Combat` class):
- List of `CombatGroup` objects (attacker + blockers + defenders)
- `defenders` set (players, planeswalkers, battles that can be attacked)
- `attackingPlayerId` - who declared attackers
- Combat state tracked per permanent:
- `attacking` flag
- `blocking` count and `minBlockedBy`/`maxBlockedBy` constraints
**Combat mechanics:**
- Declare attackers step: Players declare which creatures attack which defenders
- Declare blockers step: Defending player declares which creatures block
- Combat damage assignment: Power values, deathtouch, first strike, double strike
- `useToughnessForDamage` flag - some effects let creatures use toughness for damage instead
- Combat damage dealt to creatures = damage counters on permanents, can be lethal (≥ toughness)
- Protection rules checked via `ProtectedByOpponentPredicate`
- Flying/evasion checked via `FlyingEffect` (RestrictionEffect)
- Banding tracked via `bandedCards` list
- Requirement effects (`RequirementEffect`) for "must attack/block" mechanics
**Key events:**
- DECLARE_ATTACKER, ATTACKER_DECLARED
- DECLARE_BLOCKER, BLOCKER_DECLARED, CREATURE_BLOCKED
- COMBAT_DAMAGE_STEP
### 5. STACK & PRIORITY
**Stack implementation** (`SpellStack` extends ArrayDeque):
- LIFO structure (newest spell on top)
- Spell/StackAbility objects on stack
- `resolve()` method executed when all players pass
- `counter()` method removes from stack (with replacement effects)
**Spell execution:**
- Cast spell: Card → Spell object (Zone.STACK)
- Check targets before casting (some spells can be non-targeted)
- Spell can be replaced (replacement effects on CAST_SPELL event)
- On resolution: spell's ability executes, then spell moves to graveyard
- Spells on stack can be copied, countered, have new targets chosen
**Priority passing:**
- Each player gets priority in turn order
- Player can cast spells, activate abilities, or pass priority
- When all pass with empty stack → next phase
- When all pass with non-empty stack → resolve top object
### 6. TARGETING SYSTEM
**Target interface** (`Target` class hierarchy):
- `canChoose()` - can player choose from legal targets?
- `possibleTargets()` - returns list of valid target objects
- Supports minX/maxX for "up to" targets
- Target validation before spell cast (`isChosen()`, `isChoiceCompleted()`)
- Different target types:
- `TargetPermanent` - battlefield permanents
- `TargetCard` - cards in any zone
- `TargetPlayer` - player selection
- `TargetSpell` - stack spells only
- Many common variants (TargetCreaturePermanent, TargetOpponent, etc.)
**Target validation on cast:**
- Spells with targets check for legal targets before resolving
- Non-targeted spells (no "target" word) can't be hexproof'd
- "Choose" targets on resolution without target validation
- Replacement effects can change targets or make spells illegal
### 7. STATE-BASED ACTIONS
**Checked via** `checkStateBasedActions()` - called frequently:
- Player loses if life ≤ 0 (or 10 poison counters)
- Player loses if deck empty (on draw attempt)
- Creatures with 0 or less toughness die
- Legendary rule: Only one legend with same name per player
- Equipment/Aura fall off if legal attachment gone
- Copied spells cease to exist if not on stack/battlefield
- Planeswalkers with 0 loyalty are put to graveyard
- Players with no turns in turn order are removed (Commander)
- Dungeon rooms advance or remove when not actively triggered
- Shield counters, stun counters, finality counters have mechanical effects
### 8. EQUIPMENT & AURA ATTACHMENT
**Attachment system** (`attachedTo` field on Permanent):
- Equipment: `EquipAbility` - sorcery-speed, costs mana, attaches to creature you control
- Aura: Cast on ETB, target at cast time, reattach on zone change via replacement
- Attachment validation:
- Aura must have legal target when attached (`AuraReplacementEffect`)
- Equipment detaches if creature leaves battlefield
- Falls off on UNATTACH event
- Aura swap, banding, pairing tracked similarly
### 9. PLANESWALKER SYSTEM
**Loyalty mechanics** (`LoyaltyAbility` class):
- `PayLoyaltyCost` - static costs (+X, -Y counters)
- `PayVariableLoyaltyCost` - variable loyalty costs
- Each loyalty ability: sorcery timing, activate once per turn if you control it
- Loyalty changes tracked via counters (`CounterType.LOYALTY`)
- SBA: Planeswalker with 0 loyalty is put to graveyard
- Carth the Lion: Cost modification (static cost increased by +1)
- Loyalty counters can be replaced via `PreventionEffect` and modification
### 10. REPLACEMENT EFFECTS
**Core replacement flow:**
1. Event is about to happen (e.g., creature entering battlefield)
2. `getReplacementEffects()` list is checked
3. `checksEventType()` filters for relevant events
4. `applies()` checks source-specific conditions
5. `replaceEvent()` modifies or cancels event
6. If replacement happens, original event doesn't fire
**Scope rules** (614.12):
- Some replacements only apply if source is on battlefield at time of event
- `scopeRelevant` flag triggers scope checks
- Bounding function prevents infinite recursion
### 11. X-COST SPELLS
**Variable mana cost** (`VariableManaCost` class):
- `{X}` announced before paying mana
- `xValue` - final X amount after replacement effects
- `xPay` - total mana to pay (includes multiples like {X}{X})
- Can have `minX`/`maxX` bounds ("X can't be greater than...")
- X replaced before mana payment via events
- On resolution, X value still accessible for effects
**In abilities:**
- Replacement effects can modify X announcement
- Cost modifiers can increase/decrease X
- Some effects announce X as part of ability (e.g., "look at X cards")
### 12. MODAL SPELLS
**Mode selection** (`Modes`/`Mode` classes):
- Spells can have multiple modes
- Player chooses 1+ modes before casting (spell text defines)
- `Modes.getSelectedModes()` returns chosen modes
- `Mode` contains effects for that mode only
- Modal spells can choose same mode twice
- Modes apply their effects independently on resolution
### 13. COPY EFFECTS
**Spell copying:**
- `CopyEffect` - ReplacementEffect on CAST_SPELL or ability trigger
- `createCopyOnStack()` - creates new Spell with same abilities, can choose new targets
- Copied spells can be countered separately
- Copied spell ceases to exist if it leaves stack (SBA)
**Permanent copying:**
- Token created on battlefield with copied permanent's attributes
- Attributes copied via Layer 1 (CopyEffects)
- Copy effect can modify copied attributes (via `CopyApplier`)
- Tokens inherit P/T, types, abilities at time of copy
### 14. TRIGGERED ABILITIES
**Trigger detection:**
- Events fire via `fireEvent()` / `raiseEvent()` in game
- Watchers observe events and track state
- Triggered abilities check via event + condition
- On priority pass (603.3): triggered abilities are put on stack
**Watcher system** (84+ watchers in common):
- `Watcher` extends Listener
- `watch(GameEvent, Game)` called on each event
- Watchers track:
- Creatures that attacked this turn
- Damage dealt to players
- Spells cast
- Creatures that entered/died
- Abilities that resolved
- Many other game state facts
- Watchers reset at end of turn/combat as needed
**Example watchers:**
- `AttackedThisTurnWatcher` - tracks `Set` of creatures attacked
- `AbilityResolvedWatcher` - tracks which abilities resolved
- `CardsDrawnThisTurnWatcher` - counts cards drawn per player
- `BlockedAttackerWatcher` - tracks which creatures got blocked
### 15. KEYWORD ENFORCEMENT
**Mechanically enforced keywords** (246+ keyword ability classes):
1. **Evasion/Combat Keywords:**
- Flying, Menace, Shadow, etc. → `EvasionAbility` with `RestrictionEffect` to prevent blocking
2. **Damage/Combat Keywords:**
- Deathtouch → StaticAbility (mechanical check: 1 damage = lethal on combat damage)
- Lifelink → tracked via event counters, auto-applies to damage
- Trample → check if excess damage can pass through
- Double Strike, First Strike → damage assignment ordering
- Infect → tracked as poison counters (10 = loss)
3. **Special Keywords:**
- Banding, bands with other → tracked via `bandedCards` list
- Goad → `goadingPlayers` set on permanent, forces attacks
- Phasing → `phasedIn` flag on permanent
4. **Cost/Ability Keywords:**
- Equip, Entwine, Buyback → Cost modifications
- Flashback, Evoke, Prowess → TriggeredAbility
5. **Other:**
- Regenerate → `RegenerateSourceEffect` replaces destruction
- Haste/Summoning sickness → `controlledFromStartOfControllerTurn` flag
- Legendary → SBA checks unique names
- Transform → `transformed` flag + attributes
### 16. WATCHERS & EVENT TRACKING
**Event system** with 600+ EventType values:
**Core game events:**
- BEGINNING, PLAY_TURN, EXTRA_TURN
- CHANGE_PHASE, CHANGE_STEP
**Turn-based events:**
- UNTAP_STEP, UPKEEP_STEP, DRAW_STEP, etc. (with PRE/POST)
- BEGINNING_PHASE, COMBAT_PHASE, END_PHASE
**Permanent events:**
- ENTERS_THE_BATTLEFIELD (with SELF/CONTROL/COPY variants for replacement scope)
- TAP, UNTAP, TAPPED, UNTAPPED (with BATCH variants)
- TAPPED_FOR_MANA (for mana ability simulation)
- TRANSFORM, TRANSFORMED
- DAMAGE_PERMANENT, DAMAGED_PERMANENT
- DESTROY_PERMANENT, DESTROYED_PERMANENT
- ATTACH, ATTACHED, UNATTACH, UNATTACHED
**Card movement events:**
- ZONE_CHANGE, ZONE_CHANGE_BATCH, DRAW_CARD, DISCARD_CARD
- MILL_CARDS, MILLED_CARD, MILLED_CARDS_BATCH (with variants)
**Combat events:**
- DECLARE_ATTACKER, ATTACKER_DECLARED
- DECLARE_BLOCKER, BLOCKER_DECLARED, CREATURE_BLOCKED
- COMBAT_DAMAGE_STEP
**Ability events:**
- CAST_SPELL, SPELL_CAST
- ACTIVATE_ABILITY, ACTIVATED_ABILITY
- TRIGGERED_ABILITY, RESOLVING_ABILITY
- COPY_STACKOBJECT, COPIED_STACKOBJECT
**Damage/life events:**
- DAMAGE_PLAYER, DAMAGED_PLAYER (with BATCH variants)
- DAMAGE_CAUSES_LIFE_LOSS
- GAIN_LIFE, GAINED_LIFE
- LOSE_LIFE, LOST_LIFE, LOST_LIFE_BATCH
- DAMAGED_BATCH_FOR_PLAYERS, DAMAGED_BATCH_FOR_ONE_PLAYER
---
## Key Implementation Gaps to Check in Rust
Based on this comprehensive survey, verify your Rust engine covers:
1. **Effect layer system** - All 7 layers in correct order
2. **Replacement effect scope** - Proper battlefield checks (614.12)
3. **Continuous effect duration** - EOT, EOCombat, permanent, etc.
4. **Watcher system** - Event-driven state tracking for triggers
5. **Combat mechanics** - Evasion, first strike, trample, blocking constraints
6. **Loyalty** - Planeswalker activation tracking per-turn
7. **Equipment/Aura attachment** - Replacement on zone change, fall-off detection
8. **X-cost announcements** - Variable mana before payment
9. **Modal spells** - Mode selection and independent resolution
10. **Copy effects** - Both spell and permanent copying with attribute inheritance
11. **Trigger delays** - Triggered abilities queued until priority (603.3)
12. **All 600+ event types** - Especially zone change, damage, combat variants
13. **Keyword enforcement** - Mechanical keywords vs. reminder-text only
---
File paths for deeper reference:
- Core game loop: `/mnt/dest-btrfs/home/jc/src/mage/Mage/src/main/java/mage/game/GameImpl.java`
- Effect hierarchy: `/mnt/dest-btrfs/home/jc/src/mage/Mage/src/main/java/mage/abilities/effects/`
- Combat system: `/mnt/dest-btrfs/home/jc/src/mage/Mage/src/main/java/mage/game/combat/Combat.java`
- Stack: `/mnt/dest-btrfs/home/jc/src/mage/Mage/src/main/java/mage/game/stack/`
- Permanent: `/mnt/dest-btrfs/home/jc/src/mage/Mage/src/main/java/mage/game/permanent/PermanentImpl.java`
- Events: `/mnt/dest-btrfs/home/jc/src/mage/Mage/src/main/java/mage/game/events/GameEvent.java`
- Watchers: `/mnt/dest-btrfs/home/jc/src/mage/Mage/src/main/java/mage/watchers/` (84+ common watchers)
- Keywords: `/mnt/dest-btrfs/home/jc/src/mage/Mage/src/main/java/mage/abilities/keyword/` (246+ keywords)
total_tokens: 77883
tool_uses: 53
duration_ms: 121005
Full transcript available at: /tmp/claude-1000/-mnt-dest-btrfs-home-jc-src-mage/tasks/a2b068c.output
## Assistant
The Java engine agent completed (its findings were already incorporated). The ROADMAP.md update is done. Here's a quick recap of the document structure:
**Nine sections covering:**
| Section | Content |
|---------|---------|
| I. Critical Game Loop Gaps | Combat not wired in, triggers not stacked, layers not applied, replacements not integrated |
| II. Keyword Enforcement | 47 keywords: 10 have code (8 dormant since combat doesn't run), 37 decorative |
| III. State-Based Actions | 7 of ~13 key rules implemented; missing library-empty loss, aura fall-off, saga sacrifice |
| IV. Missing Engine Systems | 20 items in 4 tiers ranked by cards-unblocked |
| V. Effect System Gaps | 55/62 variants implemented; 940 Custom fallbacks categorized |
| VI. Per-Set Counts | FDN: 401, TLA: 253, ECL: 156, TDM: 130 customs |
| VII. Java Comparison | 20+ Java-exclusive features the Rust engine lacks |
| VIII. Phased Plan | 5 phases from "make combat work" through "eliminate all customs" |
| IX. Completed Work | Batches 1-10 recap |
The biggest takeaway: **combat integration** and **triggered ability stacking** are the two highest-leverage items — together they'd make ~1,200+ cards substantially more functional.
## User
ralph-loop:ralph-loop
/ralph-loop:ralph-loop
"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
## User
# 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:
DONE
STRICT REQUIREMENTS (DO NOT VIOLATE):
✓ Use 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.
## Assistant
I'll start by reading the ROADMAP.md to understand the current state and identify the first task to work on.
## Assistant
### Tool: Read
**Args:**
```json
{
"file_path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/ROADMAP.md"
}
```
## Assistant
**Result** (success):
```
1→# Roadmap
2→
3→This document describes implementation gaps between the Rust mtg-rl engine and the Java XMage reference engine, organized by impact on the 1,333 cards across our 4 sets (FDN, TLA, TDM, ECL).
4→
5→**Last audit: 2026-02-14** — Compared Rust engine (~14.6K lines, 21 source files) against Java XMage engine (full rules implementation).
6→
7→## Summary
8→
9→| Metric | Value |
10→|--------|-------|
11→| Cards registered | 1,333 (FDN 512, TLA 280, TDM 273, ECL 268) |
12→| `Effect::Custom` fallbacks | 747 |
13→| `StaticEffect::Custom` fallbacks | 160 |
14→| `Cost::Custom` fallbacks | 33 |
15→| **Total Custom fallbacks** | **940** |
16→| Keywords defined | 47 |
17→| Keywords mechanically enforced | 10 (but combat doesn't run, so only Haste + Defender active in practice) |
18→| State-based actions | 7 of ~20 rules implemented |
19→| Triggered abilities | Events emitted but abilities never put on stack |
20→| Replacement effects | Data structures defined but not integrated |
21→| Continuous effect layers | 7 layers defined but never applied |
22→
23→---
24→
25→## I. Critical Game Loop Gaps
26→
27→These are structural deficiencies in `game.rs` that affect ALL cards, not just specific ones.
28→
29→### A. Combat Phase Not Connected
30→
31→The `TurnManager` advances through all 13 steps (Untap → Upkeep → Draw → PrecombatMain → BeginCombat → DeclareAttackers → DeclareBlockers → FirstStrikeDamage → CombatDamage → EndCombat → PostcombatMain → EndStep → Cleanup) and the priority loop runs for all steps except Untap and Cleanup. **However**, `turn_based_actions()` only has code for 3 steps:
32→
33→| Step | Status | What's Missing |
34→|------|--------|----------------|
35→| Untap | **Implemented** | — |
36→| Upkeep | No-op | Beginning-of-upkeep trigger emission |
37→| Draw | **Implemented** | — |
38→| PrecombatMain | Priority only | Works — spells/lands can be played |
39→| BeginCombat | No-op | Begin-combat trigger emission |
40→| DeclareAttackers | **No-op** | Must prompt active player to choose attackers, tap them, emit events |
41→| DeclareBlockers | **No-op** | Must prompt defending player to choose blockers, emit events |
42→| FirstStrikeDamage | **No-op** | Must deal first/double strike damage |
43→| CombatDamage | **No-op** | Must deal regular combat damage, apply trample/deathtouch/lifelink |
44→| EndCombat | No-op | Remove-from-combat cleanup |
45→| PostcombatMain | Priority only | Works — spells/lands can be played |
46→| EndStep | No-op | End-step trigger emission |
47→| Cleanup | **Implemented** | — |
48→
49→`combat.rs` has fully implemented functions for `can_attack()`, `can_block()`, combat damage assignment (with first strike, double strike, trample, deathtouch, menace), but **none of these are ever called** from the game loop.
50→
51→**Impact:** Every creature card in all 4 sets is affected. Combat is the primary way to win games. Without it, the engine runs in a "goldfish" mode where no combat damage is ever dealt.
52→
53→**Fix:** Wire `combat.rs` into `turn_based_actions()` for DeclareAttackers, DeclareBlockers, FirstStrikeDamage, and CombatDamage. Add `choose_attackers()` and `choose_blockers()` to `PlayerDecisionMaker` trait.
54→
55→### B. Triggered Abilities Not Stacked
56→
57→Events are emitted (`GameEvent` structs) and the `AbilityStore` tracks which triggered abilities respond to which `EventType`s, but triggered abilities are **never put on the stack**. There is a TODO comment in `process_step()`:
58→
59→```rust
60→// -- Handle triggered abilities --
61→// TODO: Put triggered abilities on the stack (task #13)
62→```
63→
64→In Java XMage, after each game action, all pending triggers are gathered and placed on the stack in APNAP order (active player's triggers first, then next player). Each trigger gets its own stack entry and can be responded to.
65→
66→**Impact:** Every card with a triggered ability (ETB triggers, attack triggers, death triggers, upkeep triggers, damage triggers) silently does nothing beyond its initial cast. This affects **hundreds** of cards across all sets.
67→
68→**Fix:** After each state-based action loop, scan `AbilityStore` for triggered abilities whose trigger conditions are met by recent events. Push each onto the stack as a `StackItem`. Resolve via the existing priority loop.
69→
70→### C. Continuous Effect Layers Not Applied
71→
72→The `effects.rs` file defines a full 7-layer system matching MTG rules 613:
73→
74→1. Copy → 2. Control → 3. Text → 4. Type → 5. Color → 6. Ability → 7. P/T (with sub-layers for CDA, Set, Modify, Counters, Switch)
75→
76→`ContinuousEffect`, `EffectModification`, and `Layer`/`SubLayer` enums are all defined. But the game loop **never recalculates characteristics** using these layers. P/T boosts from lords, keyword grants, type changes — none of these are applied.
77→
78→In Java XMage, `ContinuousEffects.apply()` runs after every game action, recalculating all permanent characteristics in layer order. This is what makes lord effects, anthem effects, and ability-granting cards work.
79→
80→**Impact:** All cards with `StaticEffect::Boost`, `StaticEffect::GrantKeyword`, and other continuous effects are non-functional. ~50+ lord/anthem cards across all sets.
81→
82→**Fix:** Add a `apply_continuous_effects()` method to `Game` that iterates battlefield permanents' `static_effects` and applies them in layer order. Call it after every state-based action check.
83→
84→### D. Replacement Effects Not Integrated
85→
86→`ReplacementEffect` and `ReplacementKind` are defined in `effects.rs` with variants like `Prevent`, `ExileInstead`, `ModifyAmount`, `RedirectTarget`, `EnterTapped`, `EnterWithCounters`, `Custom`. But there is **no event interception** in the game loop — events happen without checking for replacements first.
87→
88→In Java XMage, replacement effects are checked via `getReplacementEffects()` before every event. Each replacement's `applies()` is checked, and `replaceEvent()` modifies or cancels the event.
89→
90→**Impact:** Damage prevention, death replacement ("exile instead of dying"), Doubling Season, "enters tapped" enforcement, and similar effects don't work. Affects ~30+ cards.
91→
92→**Fix:** Before each event emission, check registered replacement effects. If any apply, call `replaceEvent()` and use the modified event instead.
93→
94→---
95→
96→## II. Keyword Enforcement
97→
98→47 keywords are defined as bitflags in `KeywordAbilities`. Most are decorative.
99→
100→### Mechanically Enforced (10 keywords — in combat.rs, but combat doesn't run)
101→
102→| Keyword | Where | How |
103→|---------|-------|-----|
104→| FLYING | `combat.rs:205` | Flyers can only be blocked by flying/reach |
105→| REACH | `combat.rs:205` | Can block flyers |
106→| DEFENDER | `permanent.rs:249` | Cannot attack |
107→| HASTE | `permanent.rs:250` | Bypasses summoning sickness |
108→| FIRST_STRIKE | `combat.rs:241-248` | Damage in first-strike step |
109→| DOUBLE_STRIKE | `combat.rs:241-248` | Damage in both steps |
110→| TRAMPLE | `combat.rs:296-298` | Excess damage to defending player |
111→| DEATHTOUCH | `combat.rs:280-286` | 1 damage = lethal |
112→| MENACE | `combat.rs:216-224` | Must be blocked by 2+ creatures |
113→| INDESTRUCTIBLE | `state.rs:296` | Survives lethal damage (SBA) |
114→
115→Of these, only **Haste** and **Defender** are active in practice (checked during the priority loop for can_attack). The other 8 are only checked in combat.rs functions that are never called.
116→
117→### Not Enforced (37 keywords)
118→
119→| Keyword | Java Behavior | Rust Status |
120→|---------|--------------|-------------|
121→| VIGILANCE | Attacking doesn't cause tap | Not checked |
122→| LIFELINK | Damage → life gain | Not connected |
123→| FLASH | Cast at instant speed | Partially (blocks sorcery-speed only) |
124→| HEXPROOF | Can't be targeted by opponents | Not checked during targeting |
125→| SHROUD | Can't be targeted at all | Not checked |
126→| PROTECTION | Prevents damage/targeting/blocking/enchanting | Not checked |
127→| WARD | Counter unless cost paid | Stored as StaticEffect, not enforced |
128→| FEAR | Only blocked by black/artifact | Not checked |
129→| INTIMIDATE | Only blocked by same color/artifact | Not checked |
130→| SHADOW | Only blocked by/blocks shadow | Not checked |
131→| PROWESS | +1/+1 when noncreature spell cast | Trigger never fires |
132→| UNDYING | Return with +1/+1 counter on death | No death replacement |
133→| PERSIST | Return with -1/-1 counter on death | No death replacement |
134→| WITHER | Damage as -1/-1 counters | Not checked |
135→| INFECT | Damage as -1/-1 counters + poison | Not checked |
136→| TOXIC | Combat damage → poison counters | Not checked |
137→| UNBLOCKABLE | Can't be blocked | Not checked |
138→| CHANGELING | All creature types | Not checked in type queries |
139→| CASCADE | Exile-and-cast on cast | No trigger |
140→| CONVOKE | Tap creatures to pay | Not checked in cost payment |
141→| DELVE | Exile graveyard to pay | Not checked in cost payment |
142→| EVOLVE | +1/+1 counter on bigger ETB | No trigger |
143→| EXALTED | +1/+1 when attacking alone | No trigger |
144→| EXPLOIT | Sacrifice creature on ETB | No trigger |
145→| FLANKING | Blockers get -1/-1 | Not checked |
146→| FORESTWALK | Unblockable vs forest controller | Not checked |
147→| ISLANDWALK | Unblockable vs island controller | Not checked |
148→| MOUNTAINWALK | Unblockable vs mountain controller | Not checked |
149→| PLAINSWALK | Unblockable vs plains controller | Not checked |
150→| SWAMPWALK | Unblockable vs swamp controller | Not checked |
151→| TOTEM_ARMOR | Prevents enchanted creature death | No replacement |
152→| AFFLICT | Life loss when blocked | No trigger |
153→| BATTLE_CRY | +1/+0 to other attackers | No trigger |
154→| SKULK | Can't be blocked by greater power | Not checked |
155→| FABRICATE | Counters or tokens on ETB | No choice/trigger |
156→| STORM | Copy for each prior spell | No trigger |
157→| PARTNER | Commander pairing | Not relevant |
158→
159→---
160→
161→## III. State-Based Actions
162→
163→Checked in `state.rs:check_state_based_actions()`:
164→
165→| Rule | Description | Status |
166→|------|-------------|--------|
167→| 704.5a | Player at 0 or less life loses | **Implemented** |
168→| 704.5b | Player draws from empty library loses | **Not implemented** |
169→| 704.5c | 10+ poison counters = loss | **Implemented** |
170→| 704.5d | Token not on battlefield ceases to exist | **Not implemented** |
171→| 704.5e | 0-cost copy on stack/BF ceases to exist | **Not implemented** |
172→| 704.5f | Creature with 0 toughness → graveyard | **Implemented** |
173→| 704.5g | Lethal damage → destroy (if not indestructible) | **Implemented** |
174→| 704.5i | Planeswalker with 0 loyalty → graveyard | **Implemented** |
175→| 704.5j | Legend rule (same name) | **Implemented** |
176→| 704.5n | Aura not attached → graveyard | **Not implemented** |
177→| 704.5p | Equipment/Fortification illegal attach → unattach | **Not implemented** |
178→| 704.5r | +1/+1 and -1/-1 counter annihilation | **Implemented** |
179→| 704.5s | Saga with lore counters ≥ chapters → sacrifice | **Not implemented** |
180→
181→**Missing SBAs:** Library-empty loss, token cleanup, aura fall-off, equipment detach, saga sacrifice. These affect ~40+ cards.
182→
183→---
184→
185→## IV. Missing Engine Systems
186→
187→These require new engine architecture beyond adding match arms to existing functions.
188→
189→### Tier 1: Foundational (affect 100+ cards each)
190→
191→#### 1. Combat Integration
192→- Wire `combat.rs` functions into `turn_based_actions()` for DeclareAttackers, DeclareBlockers, CombatDamage
193→- Add `choose_attackers()` / `choose_blockers()` to `PlayerDecisionMaker`
194→- Connect lifelink (damage → life gain), vigilance (no tap), and other combat keywords
195→- **Cards affected:** Every creature in all 4 sets (~800+ cards)
196→- **Java reference:** `GameImpl.combat`, `Combat.java`, `CombatGroup.java`
197→
198→#### 2. Triggered Ability Stacking
199→- After each game action, scan for triggered abilities whose conditions match recent events
200→- Push triggers onto stack in APNAP order
201→- Resolve via existing priority loop
202→- **Cards affected:** Every card with ETB, attack, death, damage, upkeep, or endstep triggers (~400+ cards)
203→- **Java reference:** `GameImpl.checkStateAndTriggered()`, 84+ `Watcher` classes
204→
205→#### 3. Continuous Effect Layer Application
206→- Recalculate permanent characteristics after each game action
207→- Apply StaticEffect variants (Boost, GrantKeyword, CantAttack, CantBlock, etc.) in layer order
208→- Duration tracking (while-on-battlefield, until-end-of-turn, etc.)
209→- **Cards affected:** All lord/anthem effects, keyword-granting permanents (~50+ cards)
210→- **Java reference:** `ContinuousEffects.java`, 7-layer system
211→
212→### Tier 2: Key Mechanics (affect 10-30 cards each)
213→
214→#### 4. Equipment System
215→- Attach/detach mechanic (Equipment attaches to creature you control)
216→- Equip cost (activated ability, sorcery speed)
217→- Stat/keyword bonuses applied while attached (via continuous effects layer)
218→- Detach when creature leaves battlefield (SBA)
219→- **Blocked cards:** Basilisk Collar, Swiftfoot Boots, Goldvein Pick, Fishing Pole, all Equipment (~15+ cards)
220→- **Java reference:** `EquipAbility.java`, `AttachEffect.java`
221→
222→#### 5. Aura/Enchant System
223→- Auras target on cast, attach on ETB
224→- Apply continuous effects while attached (P/T boosts, keyword grants, restrictions)
225→- Fall off when enchanted permanent leaves (SBA)
226→- Enchant validation (enchant creature, enchant permanent, etc.)
227→- **Blocked cards:** Pacifism, Obsessive Pursuit, Eaten by Piranhas, Angelic Destiny (~15+ cards)
228→- **Java reference:** `AuraReplacementEffect.java`, `AttachEffect.java`
229→
230→#### 6. Replacement Effect Pipeline
231→- Before each event, check registered replacement effects
232→- `applies()` filter + `replaceEvent()` modification
233→- Support common patterns: exile-instead-of-die, enters-tapped, enters-with-counters, damage prevention
234→- Prevent infinite loops (each replacement applies once per event)
235→- **Blocked features:** Damage prevention, death replacement, Doubling Season, Undying, Persist (~30+ cards)
236→- **Java reference:** `ReplacementEffectImpl.java`, `ContinuousEffects.getReplacementEffects()`
237→
238→#### 7. X-Cost Spells
239→- Announce X before paying mana (X ≥ 0)
240→- Track X value on the stack; pass to effects on resolution
241→- Support {X}{X}, min/max X, X in activated abilities
242→- Add `choose_x_value()` to `PlayerDecisionMaker`
243→- **Blocked cards:** Day of Black Sun, Genesis Wave, Finale of Revelation, Spectral Denial (~10+ cards)
244→- **Java reference:** `VariableManaCost.java`, `ManaCostsImpl.getX()`
245→
246→#### 8. Impulse Draw (Exile-and-Play)
247→- "Exile top card, you may play it until end of [next] turn"
248→- Track exiled-but-playable cards in game state with expiration
249→- Allow casting from exile via `AsThoughEffect` equivalent
250→- **Blocked cards:** Equilibrium Adept, Kulrath Zealot, Sizzling Changeling, Burning Curiosity, Etali (~10+ cards)
251→- **Java reference:** `PlayFromNotOwnHandZoneTargetEffect.java`
252→
253→#### 9. Graveyard Casting (Flashback/Escape)
254→- Cast from graveyard with alternative cost
255→- Exile after resolution (flashback) or with escaped counters
256→- Requires `AsThoughEffect` equivalent to allow casting from non-hand zones
257→- **Blocked cards:** Cards with "Cast from graveyard, then exile" text (~6+ cards)
258→- **Java reference:** `FlashbackAbility.java`, `PlayFromNotOwnHandZoneTargetEffect.java`
259→
260→#### 10. Planeswalker System
261→- Loyalty counters as activation resource
262→- Loyalty abilities: `PayLoyaltyCost(amount)` — add or remove loyalty counters
263→- One loyalty ability per turn, sorcery speed
264→- Can be attacked (defender selection during declare attackers)
265→- Damage redirected from player to planeswalker (or direct attack)
266→- SBA: 0 loyalty → graveyard (already implemented)
267→- **Blocked cards:** Ajani, Chandra, Kaito, Liliana, Vivien, all planeswalkers (~10+ cards)
268→- **Java reference:** `LoyaltyAbility.java`, `PayLoyaltyCost.java`
269→
270→### Tier 3: Advanced Systems (affect 5-10 cards each)
271→
272→#### 11. Spell/Permanent Copy
273→- Copy spell on stack with same abilities; optionally choose new targets
274→- Copy permanent on battlefield (token with copied attributes via Layer 1)
275→- Copy + modification (e.g., "except it's a 1/1")
276→- **Blocked cards:** Electroduplicate, Rite of Replication, Self-Reflection, Flamehold Grappler (~8+ cards)
277→- **Java reference:** `CopyEffect.java`, `CreateTokenCopyTargetEffect.java`
278→
279→#### 12. Delayed Triggers
280→- "When this creature dies this turn, draw a card" — one-shot trigger registered for remainder of turn
281→- Framework: register trigger with expiration, fire when condition met, remove after
282→- **Blocked cards:** Undying Malice, Fake Your Own Death, Desperate Measures, Scarblades Malice (~5+ cards)
283→- **Java reference:** `DelayedTriggeredAbility.java`
284→
285→#### 13. Saga Enchantments
286→- Lore counters added on ETB and after draw step
287→- Chapter abilities trigger when lore counter matches chapter number
288→- Sacrifice after final chapter (SBA)
289→- **Blocked cards:** 6+ Saga cards in TDM/TLA
290→- **Java reference:** `SagaAbility.java`
291→
292→#### 14. Additional Combat Phases
293→- "Untap all creatures, there is an additional combat phase"
294→- Insert extra combat steps into the turn sequence
295→- **Blocked cards:** Aurelia the Warleader, All-Out Assault (~3 cards)
296→
297→#### 15. Conditional Cost Modifications
298→- `CostReduction` stored but not applied during cost calculation
299→- "Second spell costs {1} less", Affinity, Convoke, Delve
300→- Need cost-modification pass before mana payment
301→- **Blocked cards:** Highspire Bell-Ringer, Allies at Last, Ghalta Primal Hunger (~5+ cards)
302→- **Java reference:** `CostModificationEffect.java`, `SpellAbility.adjustCosts()`
303→
304→### Tier 4: Set-Specific Mechanics
305→
306→#### 16. Earthbend (TLA)
307→- "Look at top N, put a land to hand, rest on bottom"
308→- Similar to Explore/Impulse — top-of-library selection
309→- **Blocked cards:** Badgermole, Badgermole Cub, Ostrich-Horse, Dai Li Agents, many TLA cards (~20+ cards)
310→
311→#### 17. Behold (ECL)
312→- Reveal-and-exile-from-hand as alternative cost or condition
313→- Track "beheld" state for triggered abilities
314→- **Blocked cards:** Champion of the Weird, Champions of the Perfect, Molten Exhale, Osseous Exhale (~15+ cards)
315→
316→#### 18. ~~Vivid (ECL)~~ (DONE)
317→Color-count calculation implemented. 6 Vivid effect variants added. 6 cards fixed.
318→
319→#### 19. Renew (TDM)
320→- Counter-based death replacement (exile with counters, return later)
321→- Requires replacement effect pipeline (Tier 2, item 6)
322→- **Blocked cards:** ~5+ TDM cards
323→
324→#### 20. Endure (TDM)
325→- Put +1/+1 counters; if would die, exile with counters instead
326→- Requires replacement effect pipeline
327→- **Blocked cards:** ~3+ TDM cards
328→
329→---
330→
331→## V. Effect System Gaps
332→
333→### Implemented Effect Variants (~55 of 62)
334→
335→The following Effect variants have working `execute_effects()` match arms:
336→
337→**Damage:** DealDamage, DealDamageAll, DealDamageOpponents, DealDamageVivid
338→**Life:** GainLife, GainLifeVivid, LoseLife, LoseLifeOpponents, LoseLifeOpponentsVivid, SetLife
339→**Removal:** Destroy, DestroyAll, Exile, Sacrifice, PutOnLibrary
340→**Card Movement:** Bounce, ReturnFromGraveyard, Reanimate, DrawCards, DrawCardsVivid, DiscardCards, DiscardOpponents, Mill, SearchLibrary, LookTopAndPick
341→**Counters:** AddCounters, AddCountersSelf, AddCountersAll, RemoveCounters
342→**Tokens:** CreateToken, CreateTokenTappedAttacking, CreateTokenVivid
343→**Combat:** CantBlock, Fight, Bite, MustBlock
344→**Stats:** BoostUntilEndOfTurn, BoostPermanent, BoostAllUntilEndOfTurn, BoostUntilEotVivid, BoostAllUntilEotVivid, SetPowerToughness
345→**Keywords:** GainKeywordUntilEndOfTurn, GainKeyword, LoseKeyword, GrantKeywordAllUntilEndOfTurn, Indestructible, Hexproof
346→**Control:** GainControl, GainControlUntilEndOfTurn
347→**Utility:** TapTarget, UntapTarget, CounterSpell, Scry, AddMana, Modal, DoIfCostPaid, ChooseCreatureType, ChooseTypeAndDrawPerPermanent
348→
349→### Unimplemented Effect Variants
350→
351→| Variant | Description | Cards Blocked |
352→|---------|-------------|---------------|
353→| `GainProtection` | Target gains protection from quality | ~5 |
354→| `PreventCombatDamage` | Fog / damage prevention | ~5 |
355→| `Custom(String)` | Catch-all for untyped effects | 747 instances |
356→
357→### Custom Effect Fallback Analysis (747 Effect::Custom)
358→
359→These are effects where no typed variant exists. Grouped by what engine feature would replace them:
360→
361→| Category | Count | Sets | Engine Feature Needed |
362→|----------|-------|------|----------------------|
363→| Generic ETB stubs ("ETB effect.") | 79 | All | Triggered ability stacking |
364→| Generic activated ability stubs ("Activated effect.") | 67 | All | Proper cost+effect binding on abilities |
365→| Attack/combat triggers | 45 | All | Combat integration + triggered abilities |
366→| Cast/spell triggers | 47 | All | Triggered abilities + cost modification |
367→| Aura/equipment attachment | 28 | FDN,TDM,ECL | Equipment/Aura system |
368→| Exile-and-play effects | 25 | All | Impulse draw |
369→| Generic spell stubs ("Spell effect.") | 21 | All | Per-card typing with existing variants |
370→| Dies/sacrifice triggers | 18 | FDN,TLA | Triggered abilities |
371→| Conditional complex effects | 30+ | All | Per-card analysis; many are unique |
372→| Tapped/untap mechanics | 10 | FDN,TLA | Minor — mostly per-card fixes |
373→| Saga mechanics | 6 | TDM,TLA | Saga system |
374→| Earthbend keyword | 5 | TLA | Earthbend mechanic |
375→| Copy/clone effects | 8+ | TDM,ECL | Spell/permanent copy |
376→| Cost modifiers | 4 | FDN,ECL | Cost modification system |
377→| X-cost effects | 5+ | All | X-cost system |
378→
379→### StaticEffect::Custom Analysis (160 instances)
380→
381→| Category | Count | Engine Feature Needed |
382→|----------|-------|-----------------------|
383→| Generic placeholder ("Static effect.") | 90 | Per-card analysis; diverse |
384→| Conditional continuous ("Conditional continuous effect.") | 4 | Layer system + conditions |
385→| Dynamic P/T ("P/T = X", "+X/+X where X = ...") | 11 | Characteristic-defining abilities (Layer 7a) |
386→| Evasion/block restrictions | 5 | Restriction effects in combat |
387→| Protection effects | 4 | Protection keyword enforcement |
388→| Counter/spell protection ("Can't be countered") | 8 | Uncounterable flag or replacement effect |
389→| Keyword grants (conditional) | 4 | Layer 6 + conditions |
390→| Damage modification | 4 | Replacement effects |
391→| Transform/copy | 3 | Copy layer + transform |
392→| Mana/land effects | 3 | Mana ability modification |
393→| Cost reduction | 2 | Cost modification system |
394→| Keyword abilities (Kicker, Convoke, Delve) | 4 | Alternative/additional costs |
395→| Token doubling | 1 | Replacement effect |
396→| Trigger multiplier | 1 | Triggered ability system |
397→| Other unique effects | 16 | Per-card analysis |
398→
399→### Cost::Custom Analysis (33 instances)
400→
401→| Category | Count | Engine Feature Needed |
402→|----------|-------|-----------------------|
403→| Complex mana+tap activated abilities | 13 | Better activated ability cost parsing |
404→| Sacrifice-based activated abilities | 9 | Sacrifice-other as part of compound costs |
405→| Tap-creature costs (convoke-like) | 5 | Tap-other-creature cost variant |
406→| Exile costs (self, enchantment, graveyard) | 3 | Exile-self / exile-zone cost variants |
407→| Complex multi-part costs | 2 | Compound cost support |
408→| Discard hand | 1 | Discard-hand cost variant |
409→
410→---
411→
412→## VI. Per-Set Custom Fallback Counts
413→
414→| Set | Effect::Custom | StaticEffect::Custom | Cost::Custom | Total |
415→|-----|---------------|---------------------|-------------|-------|
416→| FDN (Foundations) | 322 | 58 | 21 | 401 |
417→| TLA (Avatar: TLA) | 197 | 54 | 2 | 253 |
418→| TDM (Tarkir: Dragonstorm) | 111 | 16 | 3 | 130 |
419→| ECL (Lorwyn Eclipsed) | 117 | 32 | 7 | 156 |
420→| **Total** | **747** | **160** | **33** | **940** |
421→
422→Detailed per-card breakdowns in `docs/{fdn,tla,tdm,ecl}-remediation.md`.
423→
424→---
425→
426→## VII. Comparison with Java XMage
427→
428→Features the Java engine has that the Rust engine lacks entirely:
429→
430→| Java Feature | Java Location | Rust Status |
431→|-------------|--------------|-------------|
432→| **84+ Watcher classes** | `mage.watchers.common/` | Basic `WatcherManager` only |
433→| **Replacement effect pipeline** | `ContinuousEffects.getReplacementEffects()` | Structs defined, not integrated |
434→| **7-layer continuous effect application** | `ContinuousEffects.apply()` | Layers defined, never applied |
435→| **RequirementEffect** (must attack/block) | `mage.abilities.effects.RequirementEffect` | No equivalent |
436→| **RestrictionEffect** (can't attack/block) | `mage.abilities.effects.RestrictionEffect` | Partial (CantAttack/CantBlock as data) |
437→| **AsThoughEffect** (play from other zones) | `mage.abilities.effects.AsThoughEffect` | No equivalent |
438→| **CostModificationEffect** | `mage.abilities.effects.CostModificationEffect` | CostReduction stored but not applied |
439→| **PreventionEffect** (damage prevention) | `mage.abilities.effects.PreventionEffect` | No equivalent |
440→| **Equipment attachment** | `EquipAbility`, `AttachEffect` | No equivalent |
441→| **Aura attachment** | `AuraReplacementEffect` | No equivalent |
442→| **Planeswalker loyalty abilities** | `LoyaltyAbility`, `PayLoyaltyCost` | No equivalent |
443→| **X-cost system** | `VariableManaCost`, `ManaCostsImpl.getX()` | No equivalent |
444→| **Spell copying** | `CopyEffect`, `CopySpellForEachItCouldTargetEffect` | No equivalent |
445→| **Delayed triggered abilities** | `DelayedTriggeredAbility` | No equivalent |
446→| **Alternative costs** (Flashback, Evoke, etc.) | `AlternativeCostSourceAbility` | Evoke stored as StaticEffect, not enforced |
447→| **Additional costs** (Kicker, Buyback, etc.) | `OptionalAdditionalCostImpl` | No equivalent |
448→| **Combat damage assignment order** | `CombatGroup.pickBlockerOrder()` | Simplified (first blocker takes all) |
449→| **Spell target legality check on resolution** | `Spell.checkTargets()` | Targets checked at cast, not re-validated |
450→| **Mana restriction** ("spend only on creatures") | `ManaPool.conditionalMana` | Not tracked |
451→| **Hybrid mana** ({B/R}, {2/G}) | `HybridManaCost` | Not modeled |
452→| **Zone change tracking** (LKI) | `getLKIBattlefield()` | No last-known-information |
453→
454→---
455→
456→## VIII. Phased Implementation Plan
457→
458→Priority ordered by cards-unblocked per effort.
459→
460→### Phase 1: Make the Engine Functional (combat + triggers)
461→
462→1. **Combat integration** — Wire `combat.rs` into `turn_based_actions()`. Add `choose_attackers()` / `choose_blockers()` to decision maker. Connect lifelink, vigilance. This single change makes every creature card functional and enables the game to have winners/losers through combat. **~800+ cards affected.**
463→
464→2. **Triggered ability stacking** — After each game action, scan for triggered abilities, push onto stack in APNAP order. This makes ETB abilities, attack triggers, death triggers, upkeep triggers, and damage triggers all work. **~400+ cards affected.**
465→
466→3. **Continuous effect layer application** — Recalculate permanent characteristics (P/T, keywords, types) by applying StaticEffect variants in layer order. Makes lord/anthem effects functional. **~50+ cards affected.**
467→
468→### Phase 2: Core Missing Mechanics
469→
470→4. **Replacement effect pipeline** — Event interception. Enables damage prevention, death replacement, enters-tapped enforcement, Undying/Persist. **~30+ cards.**
471→
472→5. **Equipment system** — Attach/detach, equip cost, stat application. **~15+ cards.**
473→
474→6. **Aura/enchant system** — Attach on ETB, apply continuous effects while attached, fall-off SBA. **~15+ cards.**
475→
476→7. **X-cost spells** — Announce X, track on stack, pass to effects. **~10+ cards.**
477→
478→8. **Impulse draw** — Exile-and-play tracking with expiration. **~10+ cards.**
479→
480→### Phase 3: Advanced Systems
481→
482→9. **Planeswalker system** — Loyalty abilities, can-be-attacked, damage redirection. **~10+ cards.**
483→
484→10. **Spell/permanent copy** — Clone spells on stack, create token copies. **~8+ cards.**
485→
486→11. **Delayed triggers** — One-shot triggered abilities with expiration. **~5+ cards.**
487→
488→12. **Graveyard casting** — Flashback, Escape, cast-from-graveyard. **~6+ cards.**
489→
490→13. **Saga enchantments** — Lore counters, chapter abilities. **~6+ cards.**
491→
492→14. **Cost modification** — Apply CostReduction during cost calculation. **~5+ cards.**
493→
494→15. **Additional combat phases** — Extra attack steps. **~3 cards.**
495→
496→### Phase 4: Set-Specific Mechanics
497→
498→16. **Earthbend** (TLA) — Top-N selection, land to hand. **~20+ cards.**
499→
500→17. **Behold** (ECL) — Reveal-from-hand alternative cost. **~15+ cards.**
501→
502→18. **Renew/Endure** (TDM) — Counter-based death replacement (needs replacement pipeline). **~8+ cards.**
503→
504→19. ~~**Vivid** (ECL)~~ — **DONE.** Color-count calculation + 6 effect variants.
505→
506→20. ~~**Modal spells**~~ — **DONE.** `Effect::Modal` + `choose_mode()`.
507→
508→21. ~~**Fight/Bite**~~ — **DONE.** `Effect::Fight` + `Effect::Bite` with dual targeting.
509→
510→22. ~~**Token stat parsing**~~ — **DONE.** `CreateToken` parses P/T and keywords from name string.
511→
512→### Phase 5: Eliminate Custom Fallbacks
513→
514→After the above systems are in place, systematically replace remaining `Custom(String)` fallbacks with typed variants:
515→
516→- **Easy wins (~100 cards):** Generic stubs ("ETB effect", "Activated effect", "Spell effect") where the effect is a simple combination of existing typed variants
517→- **Medium (~200 cards):** Cards needing one of the systems above (triggers, layers, combat) plus per-card typing
518→- **Hard (~50+ cards):** Cards with truly unique mechanics needing new Effect variants
519→
520→---
521→
522→## IX. Previously Completed Work
523→
524→**Batch 1-10 remediation** (2026-02-13 to 2026-02-14): Fixed ~60 cards by replacing Custom effects with typed variants. Added engine features: source-fallback for counters, Ward variant, EntersTappedUnless variant, mass-buff effects (BoostAllUntilEndOfTurn, GrantKeywordAllUntilEndOfTurn), AddCountersAll, AddCountersSelf, 7 cost implementations (RemoveCounters, Blight, ExileFromGraveyard, ExileFromHand, SacrificeOther, UntapSelf, Custom), Vivid mechanic (6 effect variants + color counting), Modal spells (Effect::Modal + ModalMode), Fight/Bite mechanics.
525→
526→See `docs/work-queue.md` for the batch-fix loop and per-set remediation docs for card-level details.
527→
```
## Assistant
## Assistant
The #1 priority is **Combat Integration** — wiring combat.rs into the game loop. This is the single highest-impact change. Let me start by reading the key engine files.
## Assistant
### Tool: Read
**Args:**
```json
{
"file_path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/combat.rs"
}
```
## Assistant
**Result** (success):
```
1→// Combat system — declare attackers, declare blockers, and combat damage.
2→//
3→// Implements the full MTG combat phase:
4→// 1. Beginning of combat (triggers)
5→// 2. Declare attackers (tap, validate legal attackers)
6→// 3. Declare blockers (validate legal blockers, blocking restrictions)
7→// 4. Combat damage (first strike, regular, trample, deathtouch)
8→// 5. End of combat (cleanup)
9→//
10→// Ported from mage.game.combat.Combat.java.
11→
12→use crate::constants::KeywordAbilities;
13→use crate::permanent::Permanent;
14→use crate::types::{ObjectId, PlayerId};
15→use serde::{Deserialize, Serialize};
16→use std::collections::HashMap;
17→
18→// ---------------------------------------------------------------------------
19→// Combat group — one attacker and its blockers
20→// ---------------------------------------------------------------------------
21→
22→/// A combat group: one attacker and its blockers.
23→#[derive(Clone, Debug, Serialize, Deserialize)]
24→pub struct CombatGroup {
25→ /// The attacking creature's ObjectId.
26→ pub attacker_id: ObjectId,
27→ /// What the attacker is attacking (player or planeswalker).
28→ pub defending_id: ObjectId,
29→ /// Whether the defender is a player (true) or planeswalker (false).
30→ pub defending_player: bool,
31→ /// Blockers assigned to this attacker, in damage assignment order.
32→ pub blockers: Vec,
33→ /// Whether this attacker is blocked (even if all blockers are removed).
34→ pub blocked: bool,
35→ /// Damage assignment: how much damage each blocker receives.
36→ pub damage_to_blockers: HashMap,
37→ /// Damage that overflows to the defending player (trample).
38→ pub trample_damage: u32,
39→}
40→
41→impl CombatGroup {
42→ pub fn new(attacker_id: ObjectId, defending_id: ObjectId, defending_player: bool) -> Self {
43→ CombatGroup {
44→ attacker_id,
45→ defending_id,
46→ defending_player,
47→ blockers: Vec::new(),
48→ blocked: false,
49→ damage_to_blockers: HashMap::new(),
50→ trample_damage: 0,
51→ }
52→ }
53→
54→ /// Add a blocker to this combat group.
55→ pub fn add_blocker(&mut self, blocker_id: ObjectId) {
56→ if !self.blockers.contains(&blocker_id) {
57→ self.blockers.push(blocker_id);
58→ self.blocked = true;
59→ }
60→ }
61→
62→ /// Whether this attacker has any blockers.
63→ pub fn is_blocked(&self) -> bool {
64→ self.blocked
65→ }
66→
67→ /// Whether this attacker is unblocked.
68→ pub fn is_unblocked(&self) -> bool {
69→ !self.blocked
70→ }
71→}
72→
73→// ---------------------------------------------------------------------------
74→// Combat state
75→// ---------------------------------------------------------------------------
76→
77→/// The complete combat state for a combat phase.
78→#[derive(Clone, Debug, Default, Serialize, Deserialize)]
79→pub struct CombatState {
80→ /// The attacking player.
81→ pub attacking_player: Option,
82→ /// All combat groups (one per attacker).
83→ pub groups: Vec,
84→ /// Set of all attacking creature IDs (for quick lookup).
85→ pub attackers: Vec,
86→ /// Map of blocker ID -> which attacker it's blocking.
87→ pub blocker_to_attacker: HashMap,
88→ /// Whether first strike damage has been dealt this combat.
89→ pub first_strike_dealt: bool,
90→ /// Whether regular combat damage has been dealt.
91→ pub regular_damage_dealt: bool,
92→}
93→
94→impl CombatState {
95→ pub fn new() -> Self {
96→ Self::default()
97→ }
98→
99→ /// Clear all combat state (at end of combat phase).
100→ pub fn clear(&mut self) {
101→ self.attacking_player = None;
102→ self.groups.clear();
103→ self.attackers.clear();
104→ self.blocker_to_attacker.clear();
105→ self.first_strike_dealt = false;
106→ self.regular_damage_dealt = false;
107→ }
108→
109→ /// Check if there are any attackers.
110→ pub fn has_attackers(&self) -> bool {
111→ !self.attackers.is_empty()
112→ }
113→
114→ /// Declare an attacker. Adds a combat group for this creature.
115→ pub fn declare_attacker(
116→ &mut self,
117→ attacker_id: ObjectId,
118→ defending_id: ObjectId,
119→ defending_player: bool,
120→ ) {
121→ self.attackers.push(attacker_id);
122→ self.groups.push(CombatGroup::new(attacker_id, defending_id, defending_player));
123→ }
124→
125→ /// Declare a blocker. Assigns it to the combat group for the attacker.
126→ pub fn declare_blocker(&mut self, blocker_id: ObjectId, attacker_id: ObjectId) {
127→ self.blocker_to_attacker.insert(blocker_id, attacker_id);
128→ for group in &mut self.groups {
129→ if group.attacker_id == attacker_id {
130→ group.add_blocker(blocker_id);
131→ return;
132→ }
133→ }
134→ }
135→
136→ /// Get the combat group for a specific attacker.
137→ pub fn group_for_attacker(&self, attacker_id: ObjectId) -> Option<&CombatGroup> {
138→ self.groups.iter().find(|g| g.attacker_id == attacker_id)
139→ }
140→
141→ /// Get a mutable reference to the combat group for a specific attacker.
142→ pub fn group_for_attacker_mut(&mut self, attacker_id: ObjectId) -> Option<&mut CombatGroup> {
143→ self.groups.iter_mut().find(|g| g.attacker_id == attacker_id)
144→ }
145→
146→ /// Check if a creature is currently attacking.
147→ pub fn is_attacking(&self, creature_id: ObjectId) -> bool {
148→ self.attackers.contains(&creature_id)
149→ }
150→
151→ /// Check if a creature is currently blocking.
152→ pub fn is_blocking(&self, creature_id: ObjectId) -> bool {
153→ self.blocker_to_attacker.contains_key(&creature_id)
154→ }
155→
156→ /// Get all defending players/planeswalkers being attacked.
157→ pub fn defenders(&self) -> Vec {
158→ let mut defenders: Vec = self.groups.iter().map(|g| g.defending_id).collect();
159→ defenders.sort();
160→ defenders.dedup();
161→ defenders
162→ }
163→
164→ /// Whether any creature has first/double strike (determines if we need
165→ /// the first strike damage step).
166→ pub fn has_first_strikers(&self, get_perm: &dyn Fn(ObjectId) -> Option) -> bool {
167→ for &id in &self.attackers {
168→ if let Some(kw) = get_perm(id) {
169→ if kw.contains(KeywordAbilities::FIRST_STRIKE)
170→ || kw.contains(KeywordAbilities::DOUBLE_STRIKE)
171→ {
172→ return true;
173→ }
174→ }
175→ }
176→ for &id in self.blocker_to_attacker.keys() {
177→ if let Some(kw) = get_perm(id) {
178→ if kw.contains(KeywordAbilities::FIRST_STRIKE)
179→ || kw.contains(KeywordAbilities::DOUBLE_STRIKE)
180→ {
181→ return true;
182→ }
183→ }
184→ }
185→ false
186→ }
187→}
188→
189→// ---------------------------------------------------------------------------
190→// Combat validation functions
191→// ---------------------------------------------------------------------------
192→
193→/// Check if a creature can legally attack.
194→pub fn can_attack(perm: &Permanent) -> bool {
195→ perm.can_attack()
196→}
197→
198→/// Check if a creature can legally block a specific attacker.
199→pub fn can_block(blocker: &Permanent, attacker: &Permanent) -> bool {
200→ if !blocker.can_block() {
201→ return false;
202→ }
203→
204→ // Flying: can only be blocked by creatures with flying or reach
205→ if attacker.has_flying() && !blocker.has_flying() && !blocker.has_reach() {
206→ return false;
207→ }
208→
209→ // TODO: Add more blocking restrictions (menace, intimidate, fear, etc.)
210→
211→ true
212→}
213→
214→/// Check if blocking assignments satisfy menace (attacker with menace must
215→/// be blocked by 2+ creatures).
216→pub fn satisfies_menace(
217→ attacker: &Permanent,
218→ blocker_count: usize,
219→) -> bool {
220→ if attacker.has_menace() && blocker_count > 0 && blocker_count < 2 {
221→ return false;
222→ }
223→ true
224→}
225→
226→// ---------------------------------------------------------------------------
227→// Combat damage assignment
228→// ---------------------------------------------------------------------------
229→
230→/// Compute combat damage for one combat group.
231→///
232→/// Returns a list of (target_id, damage_amount, is_player) tuples.
233→pub fn assign_combat_damage(
234→ group: &CombatGroup,
235→ attacker: &Permanent,
236→ blockers: &[(ObjectId, &Permanent)],
237→ is_first_strike_step: bool,
238→) -> Vec<(ObjectId, u32, bool)> {
239→ let mut results = Vec::new();
240→
241→ let has_first_strike = attacker.has_first_strike() || attacker.has_double_strike();
242→ let has_regular = !attacker.has_first_strike() || attacker.has_double_strike();
243→
244→ // Determine if this attacker deals damage in this step
245→ let deals_damage = if is_first_strike_step {
246→ has_first_strike
247→ } else {
248→ has_regular
249→ };
250→
251→ if !deals_damage {
252→ return results;
253→ }
254→
255→ let power = attacker.power().max(0) as u32;
256→ if power == 0 {
257→ return results;
258→ }
259→
260→ if group.is_unblocked() {
261→ // Unblocked: all damage goes to the defender
262→ results.push((group.defending_id, power, group.defending_player));
263→ } else if blockers.is_empty() {
264→ // Blocked but all blockers removed: damage is "blocked" (dealt to nothing)
265→ // unless the attacker has trample
266→ if attacker.has_trample() && group.defending_player {
267→ results.push((group.defending_id, power, true));
268→ }
269→ } else {
270→ // Blocked: assign damage to blockers in order
271→ let has_deathtouch = attacker.has_deathtouch();
272→ let has_trample = attacker.has_trample();
273→ let mut remaining_damage = power;
274→
275→ for &(blocker_id, blocker_perm) in blockers {
276→ if remaining_damage == 0 {
277→ break;
278→ }
279→
280→ let lethal = if has_deathtouch {
281→ // With deathtouch, 1 damage is lethal
282→ 1u32.saturating_sub(blocker_perm.damage)
283→ } else {
284→ let toughness = blocker_perm.toughness().max(0) as u32;
285→ toughness.saturating_sub(blocker_perm.damage)
286→ };
287→
288→ let damage = remaining_damage.min(lethal);
289→ if damage > 0 {
290→ results.push((blocker_id, damage, false));
291→ remaining_damage -= damage;
292→ }
293→ }
294→
295→ // Trample: excess damage goes to the defending player
296→ if remaining_damage > 0 && has_trample && group.defending_player {
297→ results.push((group.defending_id, remaining_damage, true));
298→ }
299→ }
300→
301→ results
302→}
303→
304→/// Compute blocker damage (damage dealt by blockers to the attacker).
305→pub fn assign_blocker_damage(
306→ blocker: &Permanent,
307→ _attacker_id: ObjectId,
308→ is_first_strike_step: bool,
309→) -> u32 {
310→ let has_first_strike = blocker.has_first_strike() || blocker.has_double_strike();
311→ let has_regular = !blocker.has_first_strike() || blocker.has_double_strike();
312→
313→ let deals_damage = if is_first_strike_step {
314→ has_first_strike
315→ } else {
316→ has_regular
317→ };
318→
319→ if !deals_damage {
320→ return 0;
321→ }
322→
323→ blocker.power().max(0) as u32
324→}
325→
326→#[cfg(test)]
327→mod tests {
328→ use super::*;
329→ use crate::card::CardData;
330→ use crate::constants::{CardType, KeywordAbilities};
331→
332→ fn make_creature(
333→ name: &str,
334→ power: i32,
335→ toughness: i32,
336→ keywords: KeywordAbilities,
337→ ) -> Permanent {
338→ let owner = PlayerId::new();
339→ let mut card = CardData::new(ObjectId::new(), owner, name);
340→ card.card_types = vec![CardType::Creature];
341→ card.power = Some(power);
342→ card.toughness = Some(toughness);
343→ card.keywords = keywords;
344→ Permanent::new(card, owner)
345→ }
346→
347→ #[test]
348→ fn combat_state_basics() {
349→ let mut state = CombatState::new();
350→ let attacker = ObjectId::new();
351→ let defender = PlayerId::new();
352→
353→ state.attacking_player = Some(PlayerId::new());
354→ state.declare_attacker(attacker, ObjectId(defender.0), true);
355→
356→ assert!(state.has_attackers());
357→ assert!(state.is_attacking(attacker));
358→ assert_eq!(state.groups.len(), 1);
359→ assert!(state.groups[0].is_unblocked());
360→ }
361→
362→ #[test]
363→ fn blocking() {
364→ let mut state = CombatState::new();
365→ let attacker = ObjectId::new();
366→ let blocker = ObjectId::new();
367→ let defender = ObjectId::new();
368→
369→ state.declare_attacker(attacker, defender, true);
370→ state.declare_blocker(blocker, attacker);
371→
372→ assert!(state.is_blocking(blocker));
373→ assert!(state.groups[0].is_blocked());
374→ assert_eq!(state.groups[0].blockers.len(), 1);
375→ }
376→
377→ #[test]
378→ fn unblocked_damage() {
379→ let attacker = make_creature("Bear", 2, 2, KeywordAbilities::empty());
380→ let attacker_id = attacker.id();
381→ let defender_id = ObjectId::new();
382→
383→ let group = CombatGroup::new(attacker_id, defender_id, true);
384→ let results = assign_combat_damage(&group, &attacker, &[], false);
385→
386→ assert_eq!(results.len(), 1);
387→ assert_eq!(results[0].0, defender_id);
388→ assert_eq!(results[0].1, 2);
389→ assert!(results[0].2); // is player
390→ }
391→
392→ #[test]
393→ fn blocked_damage() {
394→ let attacker = make_creature("Bear", 2, 2, KeywordAbilities::empty());
395→ let attacker_id = attacker.id();
396→ let blocker = make_creature("Wall", 0, 4, KeywordAbilities::DEFENDER);
397→ let blocker_id = blocker.id();
398→ let defender_id = ObjectId::new();
399→
400→ let mut group = CombatGroup::new(attacker_id, defender_id, true);
401→ group.add_blocker(blocker_id);
402→
403→ let results = assign_combat_damage(
404→ &group,
405→ &attacker,
406→ &[(blocker_id, &blocker)],
407→ false,
408→ );
409→
410→ assert_eq!(results.len(), 1);
411→ assert_eq!(results[0].0, blocker_id);
412→ assert_eq!(results[0].1, 2);
413→ assert!(!results[0].2); // not player
414→ }
415→
416→ #[test]
417→ fn trample_overflow() {
418→ let attacker = make_creature("Trampler", 5, 5, KeywordAbilities::TRAMPLE);
419→ let attacker_id = attacker.id();
420→ let blocker = make_creature("Bear", 2, 2, KeywordAbilities::empty());
421→ let blocker_id = blocker.id();
422→ let defender_id = ObjectId::new();
423→
424→ let mut group = CombatGroup::new(attacker_id, defender_id, true);
425→ group.add_blocker(blocker_id);
426→
427→ let results = assign_combat_damage(
428→ &group,
429→ &attacker,
430→ &[(blocker_id, &blocker)],
431→ false,
432→ );
433→
434→ // 2 damage to blocker (toughness 2), 3 trample to player
435→ assert_eq!(results.len(), 2);
436→ assert_eq!(results[0].0, blocker_id);
437→ assert_eq!(results[0].1, 2);
438→ assert_eq!(results[1].0, defender_id);
439→ assert_eq!(results[1].1, 3);
440→ }
441→
442→ #[test]
443→ fn deathtouch_minimizes_damage() {
444→ let attacker = make_creature("Deathtouch", 5, 5, KeywordAbilities::DEATHTOUCH | KeywordAbilities::TRAMPLE);
445→ let attacker_id = attacker.id();
446→ let blocker = make_creature("BigCreature", 1, 10, KeywordAbilities::empty());
447→ let blocker_id = blocker.id();
448→ let defender_id = ObjectId::new();
449→
450→ let mut group = CombatGroup::new(attacker_id, defender_id, true);
451→ group.add_blocker(blocker_id);
452→
453→ let results = assign_combat_damage(
454→ &group,
455→ &attacker,
456→ &[(blocker_id, &blocker)],
457→ false,
458→ );
459→
460→ // With deathtouch, only 1 damage needed to be lethal; rest tramples
461→ assert_eq!(results.len(), 2);
462→ assert_eq!(results[0].0, blocker_id);
463→ assert_eq!(results[0].1, 1); // deathtouch = 1 is lethal
464→ assert_eq!(results[1].0, defender_id);
465→ assert_eq!(results[1].1, 4); // 5 - 1 = 4 trample
466→ }
467→
468→ #[test]
469→ fn first_strike_timing() {
470→ let attacker = make_creature("FirstStriker", 3, 3, KeywordAbilities::FIRST_STRIKE);
471→ let attacker_id = attacker.id();
472→ let defender_id = ObjectId::new();
473→
474→ let group = CombatGroup::new(attacker_id, defender_id, true);
475→
476→ // First strike step: deals damage
477→ let results = assign_combat_damage(&group, &attacker, &[], true);
478→ assert_eq!(results.len(), 1);
479→ assert_eq!(results[0].1, 3);
480→
481→ // Regular damage step: does NOT deal damage (only has first strike)
482→ let results = assign_combat_damage(&group, &attacker, &[], false);
483→ assert_eq!(results.len(), 0);
484→ }
485→
486→ #[test]
487→ fn double_strike_both_steps() {
488→ let attacker = make_creature("DoubleStriker", 4, 4, KeywordAbilities::DOUBLE_STRIKE);
489→ let attacker_id = attacker.id();
490→ let defender_id = ObjectId::new();
491→
492→ let group = CombatGroup::new(attacker_id, defender_id, true);
493→
494→ // First strike step: deals damage
495→ let results = assign_combat_damage(&group, &attacker, &[], true);
496→ assert_eq!(results.len(), 1);
497→ assert_eq!(results[0].1, 4);
498→
499→ // Regular damage step: also deals damage
500→ let results = assign_combat_damage(&group, &attacker, &[], false);
501→ assert_eq!(results.len(), 1);
502→ assert_eq!(results[0].1, 4);
503→ }
504→
505→ #[test]
506→ fn flying_blocks() {
507→ let flyer = make_creature("Bird", 2, 2, KeywordAbilities::FLYING);
508→ let ground = make_creature("Bear", 2, 2, KeywordAbilities::empty());
509→ let reacher = make_creature("Spider", 2, 4, KeywordAbilities::REACH);
510→ let other_flyer = make_creature("Angel", 4, 4, KeywordAbilities::FLYING);
511→
512→ // Ground creature can't block flying
513→ assert!(!can_block(&ground, &flyer));
514→ // Reach creature can block flying
515→ assert!(can_block(&reacher, &flyer));
516→ // Flying creature can block flying
517→ assert!(can_block(&other_flyer, &flyer));
518→ // Ground creature can block ground creature
519→ assert!(can_block(&ground, &ground));
520→ }
521→
522→ #[test]
523→ fn menace_requires_two_blockers() {
524→ let menace = make_creature("Menace", 3, 3, KeywordAbilities::MENACE);
525→ let normal = make_creature("Bear", 2, 2, KeywordAbilities::empty());
526→
527→ // Menace with 1 blocker: not satisfied
528→ assert!(!satisfies_menace(&menace, 1));
529→ // Menace with 2 blockers: satisfied
530→ assert!(satisfies_menace(&menace, 2));
531→ // Menace with 0 blockers (unblocked): ok
532→ assert!(satisfies_menace(&menace, 0));
533→ // Normal creature with 1 blocker: satisfied
534→ assert!(satisfies_menace(&normal, 1));
535→ }
536→
537→ #[test]
538→ fn combat_clear() {
539→ let mut state = CombatState::new();
540→ state.declare_attacker(ObjectId::new(), ObjectId::new(), true);
541→ assert!(state.has_attackers());
542→ state.clear();
543→ assert!(!state.has_attackers());
544→ }
545→
546→ #[test]
547→ fn blocker_damage_timing() {
548→ let first_striker = make_creature("FS", 3, 3, KeywordAbilities::FIRST_STRIKE);
549→ let normal = make_creature("Normal", 2, 2, KeywordAbilities::empty());
550→ let attacker_id = ObjectId::new();
551→
552→ // First strike blocker deals damage in first strike step only
553→ assert_eq!(assign_blocker_damage(&first_striker, attacker_id, true), 3);
554→ assert_eq!(assign_blocker_damage(&first_striker, attacker_id, false), 0);
555→
556→ // Normal blocker deals damage in regular step only
557→ assert_eq!(assign_blocker_damage(&normal, attacker_id, true), 0);
558→ assert_eq!(assign_blocker_damage(&normal, attacker_id, false), 2);
559→ }
560→}
561→
```
## Assistant
### Tool: Read
**Args:**
```json
{
"file_path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/decision.rs"
}
```
## Assistant
**Result** (success):
```
1→// PlayerDecisionMaker trait and PlayerAction enum.
2→//
3→// This module defines the interface between the game engine and any player
4→// implementation (human, AI, random, RL agent). It lives in mtg-engine so
5→// the game loop can call it without depending on mtg-ai.
6→//
7→// Ported from mage.players.Player (Java) — only the decision/choice methods.
8→
9→use crate::constants::{ManaColor, Outcome};
10→use crate::types::{AbilityId, ObjectId, PlayerId};
11→
12→// ---------------------------------------------------------------------------
13→// Supporting types for decisions
14→// ---------------------------------------------------------------------------
15→
16→/// A single action a player can take when they have priority.
17→#[derive(Clone, Debug, PartialEq, Eq)]
18→pub enum PlayerAction {
19→ /// Pass priority (do nothing).
20→ Pass,
21→
22→ /// Cast a spell from the given zone.
23→ CastSpell {
24→ card_id: ObjectId,
25→ /// Targets chosen for the spell (may be empty for untargeted spells).
26→ targets: Vec,
27→ /// Mode choice for modal spells (0-indexed). `None` for non-modal spells.
28→ mode: Option,
29→ /// If true, the spell is cast without paying its mana cost
30→ /// (e.g. alternative cost, free cast effect).
31→ without_mana: bool,
32→ },
33→
34→ /// Activate an activated ability of a permanent or card.
35→ ActivateAbility {
36→ source_id: ObjectId,
37→ ability_id: AbilityId,
38→ /// Targets for the ability.
39→ targets: Vec,
40→ },
41→
42→ /// Play a land from hand. Only legal during main phases with priority and
43→ /// if the player has remaining land plays.
44→ PlayLand {
45→ card_id: ObjectId,
46→ },
47→
48→ /// Special actions (e.g. unmorph, suspend, companion, foretell).
49→ SpecialAction {
50→ source_id: ObjectId,
51→ action_type: SpecialActionType,
52→ },
53→
54→ /// Tap a land or mana source to pay a mana cost. Used during mana payment.
55→ ActivateManaAbility {
56→ source_id: ObjectId,
57→ ability_id: AbilityId,
58→ },
59→}
60→
61→/// Types of special actions that don't use the stack.
62→#[derive(Clone, Debug, PartialEq, Eq)]
63→pub enum SpecialActionType {
64→ TurnFaceUp,
65→ PlayFromExile,
66→ CompanionToHand,
67→ Foretell,
68→ Other(String),
69→}
70→
71→/// Describes a target requirement for a spell or ability being resolved.
72→#[derive(Clone, Debug)]
73→pub struct TargetRequirement {
74→ /// Human-readable description of what is being targeted (e.g. "target creature").
75→ pub description: String,
76→ /// Legal target object IDs.
77→ pub legal_targets: Vec,
78→ /// Minimum number of targets to choose.
79→ pub min_targets: usize,
80→ /// Maximum number of targets to choose.
81→ pub max_targets: usize,
82→ /// Whether this is a mandatory or optional target.
83→ pub required: bool,
84→}
85→
86→/// Describes a choice from a list of named options (e.g. mode selection, pile choice).
87→#[derive(Clone, Debug)]
88→pub struct NamedChoice {
89→ /// The unique key/index for this choice.
90→ pub index: usize,
91→ /// Human-readable description of the option.
92→ pub description: String,
93→}
94→
95→/// Describes an amount of damage that must be distributed among targets.
96→#[derive(Clone, Debug)]
97→pub struct DamageAssignment {
98→ /// Total damage to distribute.
99→ pub total_damage: u32,
100→ /// Objects that can receive damage.
101→ pub targets: Vec,
102→ /// Minimum damage each target must receive (usually 1 for "divide" effects,
103→ /// or the target's toughness for trample).
104→ pub minimum_per_target: Vec,
105→}
106→
107→/// Information about an attacker for blocker assignment.
108→#[derive(Clone, Debug)]
109→pub struct AttackerInfo {
110→ pub attacker_id: ObjectId,
111→ /// Which player or planeswalker is being attacked.
112→ pub defending_id: ObjectId,
113→ /// Creatures that can legally block this attacker.
114→ pub legal_blockers: Vec,
115→}
116→
117→/// Description of an unpaid mana cost component.
118→#[derive(Clone, Debug)]
119→pub struct UnpaidMana {
120→ /// Which colors can satisfy this cost component. Empty means generic.
121→ pub acceptable_colors: Vec,
122→ /// Whether this is a generic mana cost (any color/colorless works).
123→ pub is_generic: bool,
124→ /// Whether snow mana is required.
125→ pub requires_snow: bool,
126→}
127→
128→/// Information about a replacement effect that the player must choose between.
129→#[derive(Clone, Debug)]
130→pub struct ReplacementEffectChoice {
131→ pub index: usize,
132→ pub description: String,
133→ pub source_name: String,
134→}
135→
136→/// Read-only view of the game state for decision-making.
137→///
138→/// This is a reference to the actual GameState — implementations should not
139→/// need to clone or mutate it. The game engine passes this to every decision
140→/// method so the AI/player can inspect the board, hands, etc.
141→///
142→/// This is currently a placeholder. When `state.rs` is implemented (task #5),
143→/// this will become a proper type alias or wrapper around GameState.
144→pub struct GameView<'a> {
145→ _marker: std::marker::PhantomData<&'a ()>,
146→ // Will contain:
147→ // pub state: &'a GameState,
148→ // pub active_player: PlayerId,
149→ // pub priority_player: PlayerId,
150→ // pub current_step: PhaseStep,
151→ // pub turn_number: u32,
152→ // ... visibility filters per player
153→}
154→
155→impl<'a> GameView<'a> {
156→ /// Temporary constructor while GameState is not yet implemented.
157→ pub fn placeholder() -> Self {
158→ GameView {
159→ _marker: std::marker::PhantomData,
160→ }
161→ }
162→}
163→
164→// ---------------------------------------------------------------------------
165→// The trait
166→// ---------------------------------------------------------------------------
167→
168→/// The core decision-making interface for all player types.
169→///
170→/// The game engine calls these methods whenever a player needs to make a
171→/// choice. Implementations include:
172→/// - **RandomPlayer** — picks uniformly at random from legal options
173→/// - **HeuristicPlayer** — port of ComputerPlayer.java
174→/// - **MinimaxPlayer** — port of ComputerPlayer6.java with alpha-beta search
175→/// - **RLAgent** — neural network policy, action selected from observation tensor
176→/// - **HumanPlayer** — forwards choices to a UI (not in scope for mtg-rl)
177→///
178→/// All methods receive a `&GameView` providing read-only access to the full
179→/// game state. The engine guarantees that only legal options are presented
180→/// in the choice parameters.
181→///
182→/// Methods return the chosen option. If a method returns an invalid choice,
183→/// the engine will treat it as an illegal action (the exact behavior depends
184→/// on the game loop — typically the game will choose a default or pass).
185→pub trait PlayerDecisionMaker: Send + Sync {
186→ /// Called when the player has priority. Must return one of the legal actions.
187→ ///
188→ /// This is the primary decision point. The engine provides the set of
189→ /// currently legal actions (always includes `PlayerAction::Pass`).
190→ fn priority(
191→ &mut self,
192→ game: &GameView<'_>,
193→ legal_actions: &[PlayerAction],
194→ ) -> PlayerAction;
195→
196→ /// Choose targets for a spell or ability.
197→ ///
198→ /// Returns the selected target IDs. The engine validates that the returned
199→ /// targets are within `requirement.legal_targets` and the count is within
200→ /// `[min_targets, max_targets]`.
201→ fn choose_targets(
202→ &mut self,
203→ game: &GameView<'_>,
204→ outcome: Outcome,
205→ requirement: &TargetRequirement,
206→ ) -> Vec;
207→
208→ /// Yes/no decision (e.g. "Do you want to pay {2}?", "Sacrifice a creature?").
209→ ///
210→ /// `outcome` indicates whether saying "yes" is generally good or bad for
211→ /// the player, helping AI implementations decide without deep evaluation.
212→ fn choose_use(
213→ &mut self,
214→ game: &GameView<'_>,
215→ outcome: Outcome,
216→ message: &str,
217→ ) -> bool;
218→
219→ /// Choose a mode for a modal spell or ability.
220→ ///
221→ /// `modes` lists the available mode descriptions. Returns the 0-based
222→ /// index of the chosen mode. For spells that choose multiple modes,
223→ /// this will be called once per mode selection.
224→ fn choose_mode(
225→ &mut self,
226→ game: &GameView<'_>,
227→ modes: &[NamedChoice],
228→ ) -> usize;
229→
230→ /// Choose attackers during the declare attackers step.
231→ ///
232→ /// `possible_attackers` lists all creatures that can legally attack.
233→ /// Returns the IDs of creatures that will attack, along with the
234→ /// defender each attacks (player or planeswalker).
235→ fn select_attackers(
236→ &mut self,
237→ game: &GameView<'_>,
238→ possible_attackers: &[ObjectId],
239→ possible_defenders: &[ObjectId],
240→ ) -> Vec<(ObjectId, ObjectId)>;
241→
242→ /// Choose blockers during the declare blockers step.
243→ ///
244→ /// `attackers` describes each attacking creature and which creatures
245→ /// can legally block it. Returns pairs of (blocker_id, attacker_id).
246→ fn select_blockers(
247→ &mut self,
248→ game: &GameView<'_>,
249→ attackers: &[AttackerInfo],
250→ ) -> Vec<(ObjectId, ObjectId)>;
251→
252→ /// Distribute damage among multiple targets.
253→ ///
254→ /// Used for effects like "deal 5 damage divided as you choose" and
255→ /// trample damage assignment. Returns (target_id, damage_amount) pairs
256→ /// that must sum to `assignment.total_damage`.
257→ fn assign_damage(
258→ &mut self,
259→ game: &GameView<'_>,
260→ assignment: &DamageAssignment,
261→ ) -> Vec<(ObjectId, u32)>;
262→
263→ /// Mulligan decision. Returns `true` to mulligan (shuffle and draw one fewer),
264→ /// `false` to keep the current hand.
265→ fn choose_mulligan(
266→ &mut self,
267→ game: &GameView<'_>,
268→ hand: &[ObjectId],
269→ ) -> bool;
270→
271→ /// After mulliganing, choose which cards to put on the bottom of the library.
272→ ///
273→ /// `hand` is the current hand, `count` is how many cards must be put back.
274→ /// Returns exactly `count` card IDs from `hand`.
275→ fn choose_cards_to_put_back(
276→ &mut self,
277→ game: &GameView<'_>,
278→ hand: &[ObjectId],
279→ count: usize,
280→ ) -> Vec;
281→
282→ /// Choose cards to discard (e.g. for hand size limit or discard effects).
283→ ///
284→ /// `hand` is the current hand, `count` is how many must be discarded.
285→ /// Returns exactly `count` card IDs from `hand`.
286→ fn choose_discard(
287→ &mut self,
288→ game: &GameView<'_>,
289→ hand: &[ObjectId],
290→ count: usize,
291→ ) -> Vec;
292→
293→ /// Choose a number within a range (e.g. X in mana costs, number of counters).
294→ fn choose_amount(
295→ &mut self,
296→ game: &GameView<'_>,
297→ message: &str,
298→ min: u32,
299→ max: u32,
300→ ) -> u32;
301→
302→ /// Pay a mana cost by activating mana abilities.
303→ ///
304→ /// `unpaid` describes the remaining unpaid portion of the cost.
305→ /// `mana_abilities` lists the mana abilities that can be activated.
306→ /// Returns the mana ability action to activate, or `None` to stop
307→ /// paying (which may result in the spell being canceled).
308→ fn choose_mana_payment(
309→ &mut self,
310→ game: &GameView<'_>,
311→ unpaid: &UnpaidMana,
312→ mana_abilities: &[PlayerAction],
313→ ) -> Option;
314→
315→ /// Choose between multiple replacement effects that want to modify the
316→ /// same event (e.g. multiple "if this would die" effects).
317→ ///
318→ /// Returns the index of the chosen replacement effect.
319→ fn choose_replacement_effect(
320→ &mut self,
321→ game: &GameView<'_>,
322→ effects: &[ReplacementEffectChoice],
323→ ) -> usize;
324→
325→ /// Choose which pile to take when a card splits into two piles
326→ /// (e.g. Fact or Fiction). Returns `true` for pile 1, `false` for pile 2.
327→ fn choose_pile(
328→ &mut self,
329→ game: &GameView<'_>,
330→ outcome: Outcome,
331→ message: &str,
332→ pile1: &[ObjectId],
333→ pile2: &[ObjectId],
334→ ) -> bool;
335→
336→ /// Generic choice from a list of named options. Used for miscellaneous
337→ /// decisions like choosing a color, creature type, card name, etc.
338→ fn choose_option(
339→ &mut self,
340→ game: &GameView<'_>,
341→ outcome: Outcome,
342→ message: &str,
343→ options: &[NamedChoice],
344→ ) -> usize;
345→
346→ /// Called at the start of each game to let the implementation initialize
347→ /// any per-game state. Default implementation does nothing.
348→ fn on_game_start(&mut self, _game: &GameView<'_>, _player_id: PlayerId) {}
349→
350→ /// Called at the end of the game. Implementations can use this for
351→ /// learning (RL reward signal) or cleanup.
352→ fn on_game_end(&mut self, _game: &GameView<'_>, _won: bool) {}
353→}
354→
```
## Assistant
### Tool: Read
**Args:**
```json
{
"file_path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/game.rs"
}
```
## Assistant
**Result** (error):
```
File content (54632 tokens) exceeds maximum allowed tokens (25000). Please use offset and limit parameters to read specific portions of the file, or use the GrepTool to search for specific content.
```
## Assistant
## Assistant
The `PlayerDecisionMaker` trait already has `select_attackers()` and `select_blockers()`! That's great. Let me read the relevant parts of game.rs - the turn_based_actions and related areas.
## Assistant
### Tool: Read
**Args:**
```json
{
"file_path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/game.rs",
"limit": 100,
"offset": 1
}
```
## Assistant
**Result** (success):
```
1→// Game — the top-level game runner.
2→//
3→// The Game struct ties together the GameState, TurnManager, and
4→// PlayerDecisionMaker implementations to run a complete game of Magic.
5→//
6→// The game loop follows the MTG comprehensive rules:
7→// 1. Advance to the next step/phase
8→// 2. Process turn-based actions for that step
9→// 3. Check state-based actions (loop until none found)
10→// 4. Put triggered abilities on the stack
11→// 5. Give active player priority
12→// 6. Players pass priority or take actions
13→// 7. When all pass with empty stack → advance; with items → resolve top
14→//
15→// Ported from mage.game.GameImpl.
16→
17→use crate::abilities::{Cost, Effect};
18→use crate::constants::AbilityType;
19→use crate::card::CardData;
20→use crate::constants::PhaseStep;
21→use crate::counters::CounterType;
22→use crate::decision::PlayerDecisionMaker;
23→use crate::permanent::Permanent;
24→use crate::state::{GameState, StateBasedActions};
25→use crate::turn::{has_priority, PriorityTracker, TurnManager};
26→use crate::types::{AbilityId, ObjectId, PlayerId};
27→use crate::watchers::WatcherManager;
28→use std::collections::HashMap;
29→
30→/// Maximum number of SBA iterations before we bail out (safety valve).
31→const MAX_SBA_ITERATIONS: u32 = 100;
32→
33→/// Maximum number of turns before the game is declared a draw (safety valve).
34→const MAX_TURNS: u32 = 500;
35→
36→/// Configuration for a new game.
37→pub struct GameConfig {
38→ /// Player names and their decks (as CardData vectors).
39→ pub players: Vec,
40→ /// Starting life total (default 20).
41→ pub starting_life: i32,
42→}
43→
44→/// Configuration for a single player in a new game.
45→pub struct PlayerConfig {
46→ pub name: String,
47→ pub deck: Vec,
48→}
49→
50→/// The result of a completed game.
51→#[derive(Clone, Debug)]
52→pub struct GameResult {
53→ /// The winner, or None for a draw.
54→ pub winner: Option,
55→ /// Final turn number.
56→ pub turn_number: u32,
57→ /// How the game ended.
58→ pub reason: GameEndReason,
59→}
60→
61→#[derive(Clone, Debug)]
62→pub enum GameEndReason {
63→ /// A player lost (life, poison, decked, etc.).
64→ PlayerLost,
65→ /// A player conceded.
66→ Concession,
67→ /// All opponents lost simultaneously.
68→ LastPlayerStanding,
69→ /// Maximum turns reached (safety valve).
70→ MaxTurnsReached,
71→ /// The game was a draw.
72→ Draw,
73→}
74→
75→/// The main game runner. Holds the game state and drives the game loop.
76→pub struct Game {
77→ /// The game state.
78→ pub state: GameState,
79→ /// The turn manager.
80→ pub turn_manager: TurnManager,
81→ /// Player decision-makers, keyed by PlayerId.
82→ decision_makers: HashMap>,
83→ /// Watcher manager for event tracking.
84→ pub watchers: WatcherManager,
85→}
86→
87→impl Game {
88→ /// Create a new two-player game.
89→ pub fn new_two_player(
90→ config: GameConfig,
91→ mut decision_makers: Vec<(PlayerId, Box)>,
92→ ) -> Self {
93→ assert_eq!(config.players.len(), 2, "Two-player game requires exactly 2 players");
94→ assert_eq!(decision_makers.len(), 2, "Two-player game requires exactly 2 decision makers");
95→
96→ // Create player IDs
97→ let player_ids: Vec = decision_makers.iter().map(|(id, _)| *id).collect();
98→
99→ // Build game state
100→ let player_names: Vec<(&str, PlayerId)> = config
```
## Assistant
### Tool: Read
**Args:**
```json
{
"file_path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/game.rs",
"limit": 100,
"offset": 100
}
```
## Assistant
**Result** (success):
```
100→ let player_names: Vec<(&str, PlayerId)> = config
101→ .players
102→ .iter()
103→ .zip(player_ids.iter())
104→ .map(|(pc, &id)| (pc.name.as_str(), id))
105→ .collect();
106→ let mut state = GameState::new(&player_names);
107→
108→ // Set starting life
109→ for player in state.players.values_mut() {
110→ player.life = config.starting_life;
111→ }
112→
113→ // Build card store and libraries from decks
114→ for (player_config, &player_id) in config.players.iter().zip(player_ids.iter()) {
115→ let mut card_ids = Vec::with_capacity(player_config.deck.len());
116→ for card in &player_config.deck {
117→ let mut card_data = card.clone();
118→ card_data.owner = player_id;
119→ let card_id = card_data.id;
120→ state.card_store.insert(card_data);
121→ card_ids.push(card_id);
122→ }
123→ for &card_id in &card_ids {
124→ state.object_zones.insert(
125→ card_id,
126→ crate::state::ZoneLocation {
127→ zone: crate::constants::Zone::Library,
128→ controller: Some(player_id),
129→ },
130→ );
131→ }
132→ let player = state.players.get_mut(&player_id).unwrap();
133→ for card_id in card_ids {
134→ player.library.put_on_bottom(card_id);
135→ }
136→ }
137→
138→ // Build turn manager
139→ let turn_manager = TurnManager::new(player_ids.clone());
140→
141→ // Build decision maker map
142→ let dm_map: HashMap> =
143→ decision_makers.drain(..).collect();
144→
145→ Game {
146→ state,
147→ turn_manager,
148→ decision_makers: dm_map,
149→ watchers: WatcherManager::new(),
150→ }
151→ }
152→
153→ /// Run the game to completion. Returns the game result.
154→ pub fn run(&mut self) -> GameResult {
155→ // Shuffle libraries
156→ let mut rng = rand::thread_rng();
157→ for player in self.state.players.values_mut() {
158→ player.library.shuffle(&mut rng);
159→ }
160→
161→ // Draw opening hands (7 cards each)
162→ let player_ids: Vec = self.state.turn_order.clone();
163→ for &pid in &player_ids {
164→ self.draw_cards(pid, 7);
165→ }
166→
167→ // London mulligan phase
168→ self.london_mulligan(&player_ids);
169→
170→ // Notify decision makers of game start
171→ let view = crate::decision::GameView::placeholder();
172→ for (&pid, dm) in &mut self.decision_makers {
173→ dm.on_game_start(&view, pid);
174→ }
175→
176→ // Main game loop
177→ loop {
178→ // Check safety valves
179→ if self.turn_manager.turn_number > MAX_TURNS {
180→ return GameResult {
181→ winner: None,
182→ turn_number: self.turn_manager.turn_number,
183→ reason: GameEndReason::MaxTurnsReached,
184→ };
185→ }
186→
187→ // Process current step
188→ self.process_step();
189→
190→ // Check if game should end
191→ if let Some(result) = self.check_game_end() {
192→ // Notify decision makers of game end
193→ let view = crate::decision::GameView::placeholder();
194→ for (&pid, dm) in &mut self.decision_makers {
195→ let won = result.winner == Some(pid);
196→ dm.on_game_end(&view, won);
197→ }
198→ return result;
199→ }
```
## Assistant
### Tool: Read
**Args:**
```json
{
"file_path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/game.rs",
"limit": 200,
"offset": 340
}
```
## Assistant
**Result** (success):
```
340→ }
341→
342→ /// Process the current step: turn-based actions, SBAs, triggers, priority.
343→ fn process_step(&mut self) {
344→ let step = self.state.current_step;
345→ let active = self.state.active_player;
346→
347→ // -- Turn-based actions --
348→ self.turn_based_actions(step, active);
349→
350→ // -- Check state-based actions (loop until stable) --
351→ self.process_state_based_actions();
352→
353→ // -- Handle triggered abilities --
354→ // TODO: Put triggered abilities on the stack (task #13)
355→
356→ // -- Priority loop --
357→ if has_priority(step) {
358→ self.priority_loop();
359→ }
360→ }
361→
362→ /// Execute turn-based actions for a step.
363→ fn turn_based_actions(&mut self, step: PhaseStep, active_player: PlayerId) {
364→ match step {
365→ PhaseStep::Untap => {
366→ // Untap all permanents controlled by the active player
367→ for perm in self.state.battlefield.iter_mut() {
368→ if perm.controller == active_player {
369→ perm.untap();
370→ perm.remove_summoning_sickness();
371→ }
372→ }
373→ // Empty mana pool (normally happens at end of each step, but
374→ // also at untap for clarity)
375→ if let Some(player) = self.state.players.get_mut(&active_player) {
376→ player.mana_pool.clear();
377→ }
378→ }
379→ PhaseStep::Draw => {
380→ // Active player draws a card
381→ // Skip draw on turn 1 for the starting player (two-player rule)
382→ if self.turn_manager.turn_number > 1 || self.state.turn_order[0] != active_player {
383→ self.draw_cards(active_player, 1);
384→ }
385→ }
386→ PhaseStep::Cleanup => {
387→ // Discard down to max hand size
388→ let discard_info = self
389→ .state
390→ .players
391→ .get(&active_player)
392→ .map(|p| {
393→ let count = p.discard_count();
394→ let hand: Vec = p.hand.iter().copied().collect();
395→ (count, hand)
396→ });
397→
398→ if let Some((discard_count, hand_cards)) = discard_info {
399→ if discard_count > 0 {
400→ let view = crate::decision::GameView::placeholder();
401→ let to_discard = if let Some(dm) =
402→ self.decision_makers.get_mut(&active_player)
403→ {
404→ dm.choose_discard(&view, &hand_cards, discard_count as usize)
405→ } else {
406→ hand_cards
407→ .iter()
408→ .rev()
409→ .take(discard_count as usize)
410→ .copied()
411→ .collect()
412→ };
413→ for card_id in to_discard {
414→ if let Some(player) =
415→ self.state.players.get_mut(&active_player)
416→ {
417→ player.hand.remove(card_id);
418→ }
419→ self.move_card_to_graveyard(card_id, active_player);
420→ }
421→ }
422→ }
423→ // Remove damage from all creatures and clear "until end of turn" effects
424→ for perm in self.state.battlefield.iter_mut() {
425→ if perm.is_creature() {
426→ perm.clear_damage();
427→ }
428→ // Clear granted keywords (from GainKeywordUntilEndOfTurn, Indestructible, Hexproof)
429→ perm.granted_keywords = crate::constants::KeywordAbilities::empty();
430→ perm.removed_keywords = crate::constants::KeywordAbilities::empty();
431→ // Remove "can't block" sentinel counters
432→ perm.counters.remove_all(&crate::counters::CounterType::Custom("cant_block".into()));
433→ // Revert temporary control changes (GainControlUntilEndOfTurn)
434→ if let Some(orig) = perm.original_controller.take() {
435→ perm.controller = orig;
436→ }
437→ }
438→ // Empty mana pools
439→ for player in self.state.players.values_mut() {
440→ player.mana_pool.clear();
441→ }
442→ }
443→ _ => {
444→ // Other steps: empty mana pool at step transition (simplified)
445→ // In full rules, mana empties at end of each step/phase.
446→ }
447→ }
448→ }
449→
450→ /// Run the priority loop: players take actions or pass until the stack
451→ /// resolves or the step ends.
452→ fn priority_loop(&mut self) {
453→ let active = self.state.active_player;
454→ let player_count = self.state.active_players().len() as u32;
455→ if player_count == 0 {
456→ return;
457→ }
458→
459→ let mut tracker = PriorityTracker::new(active, player_count);
460→
461→ loop {
462→ // Check SBAs each time through the loop
463→ self.process_state_based_actions();
464→
465→ // Check if game should end
466→ if self.state.should_end() {
467→ return;
468→ }
469→
470→ // Give current priority player a chance to act
471→ let priority_player = tracker.current;
472→ self.state.priority_player = priority_player;
473→
474→ // Build legal actions
475→ let legal_actions = self.compute_legal_actions(priority_player);
476→
477→ // Ask the decision maker
478→ let action = {
479→ let view = crate::decision::GameView::placeholder();
480→ if let Some(dm) = self.decision_makers.get_mut(&priority_player) {
481→ dm.priority(&view, &legal_actions)
482→ } else {
483→ crate::decision::PlayerAction::Pass
484→ }
485→ };
486→
487→ match action {
488→ crate::decision::PlayerAction::Pass => {
489→ if tracker.pass() {
490→ // All players passed
491→ if self.state.stack.is_empty() {
492→ // Stack is empty — step ends
493→ return;
494→ } else {
495→ // Resolve top of stack
496→ self.resolve_top_of_stack();
497→ tracker.reset();
498→ // Priority goes back to active player
499→ tracker.current = active;
500→ }
501→ } else {
502→ // Move priority to next player
503→ tracker.current = self.state.next_player(priority_player);
504→ }
505→ }
506→ crate::decision::PlayerAction::PlayLand { card_id } => {
507→ self.play_land(priority_player, card_id);
508→ tracker.reset();
509→ // Priority stays with the active player after playing a land
510→ tracker.current = priority_player;
511→ }
512→ crate::decision::PlayerAction::CastSpell { card_id, .. } => {
513→ self.cast_spell(priority_player, card_id);
514→ tracker.reset();
515→ tracker.current = priority_player;
516→ }
517→ crate::decision::PlayerAction::ActivateAbility { source_id, ability_id, targets } => {
518→ self.activate_ability(priority_player, source_id, ability_id, &targets);
519→ tracker.reset();
520→ tracker.current = priority_player;
521→ }
522→ crate::decision::PlayerAction::ActivateManaAbility { source_id, ability_id } => {
523→ // Mana abilities don't use the stack — resolve immediately
524→ self.activate_mana_ability(priority_player, source_id, ability_id);
525→ // Mana abilities don't reset priority passes
526→ }
527→ _ => {
528→ // Other actions (special actions)
529→ tracker.reset();
530→ tracker.current = priority_player;
531→ }
532→ }
533→ }
534→ }
535→
536→ /// Compute the legal actions for a player who has priority.
537→ fn compute_legal_actions(&self, player_id: PlayerId) -> Vec {
538→ let mut actions = vec![crate::decision::PlayerAction::Pass];
539→
```
## Assistant
## Assistant
Now let me check the GameState struct for combat_state and the damage-dealing functions.
## Assistant
### Tool: Grep
**Args:**
```json
{
"-C": 2,
"output_mode": "content",
"path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/game.rs",
"pattern": "combat_state|CombatState|fn deal_damage|fn apply_damage|fn damage_player"
}
```
## Assistant
**Result** (success):
```
No matches found
```
## Assistant
### Tool: Grep
**Args:**
```json
{
"-C": 3,
"output_mode": "content",
"path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/state.rs",
"pattern": "combat_state|CombatState"
}
```
## Assistant
**Result** (success):
```
No matches found
```
## Assistant
### Tool: Grep
**Args:**
```json
{
"-C": 3,
"output_mode": "content",
"path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/",
"pattern": "fn deal_damage|fn damage_player|fn damage_creature|fn damage_permanent|fn apply_damage"
}
```
## Assistant
**Result** (success):
```
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/abilities.rs-646- }
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/abilities.rs-647-
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/abilities.rs-648- /// "Deal N damage to target."
mtg-rl/mtg-engine/src/abilities.rs:649: pub fn deal_damage(amount: u32) -> Self {
mtg-rl/mtg-engine/src/abilities.rs-650- Effect::DealDamage { amount }
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/abilities.rs-651- }
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/abilities.rs-652-
--
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/abilities.rs-890- }
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/abilities.rs-891-
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/abilities.rs-892- /// Vivid -- Deal damage equal to colors among permanents you control.
mtg-rl/mtg-engine/src/abilities.rs:893: pub fn deal_damage_vivid() -> Self { Effect::DealDamageVivid }
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/abilities.rs-894- /// Vivid -- Gain life equal to colors among permanents you control.
mtg-rl/mtg-engine/src/abilities.rs-895- pub fn gain_life_vivid() -> Self { Effect::GainLifeVivid }
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/abilities.rs-896- /// Vivid -- Target gets +X/+X until EOT where X = colors among permanents.
--
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/events.rs-417-
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/events.rs-418-impl GameEvent {
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/events.rs-419- /// Create a damage-to-player event.
mtg-rl/mtg-engine/src/events.rs:420: pub fn damage_player(
mtg-rl/mtg-engine/src/events.rs-421- target_player: PlayerId,
mtg-rl/mtg-engine/src/events.rs-422- source: ObjectId,
mtg-rl/mtg-engine/src/events.rs-423- amount: u32,
--
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/events.rs-431- }
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/events.rs-432-
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/events.rs-433- /// Create a damage-to-permanent event.
mtg-rl/mtg-engine/src/events.rs:434: pub fn damage_permanent(
mtg-rl/mtg-engine/src/events.rs-435- target_permanent: ObjectId,
mtg-rl/mtg-engine/src/events.rs-436- source: ObjectId,
mtg-rl/mtg-engine/src/events.rs-437- amount: u32,
--
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/events.rs-653- }
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/events.rs-654-
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/events.rs-655- #[test]
mtg-rl/mtg-engine/src/events.rs:656: fn damage_player_convenience() {
mtg-rl/mtg-engine/src/events.rs-657- let player = PlayerId::new();
mtg-rl/mtg-engine/src/events.rs-658- let source = ObjectId::new();
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/events.rs-659-
--
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/permanent.rs-258- // ── Damage ─────────────────────────────────────────────────────────
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/permanent.rs-259-
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/permanent.rs-260- /// Apply damage to this permanent. Returns the actual damage dealt.
mtg-rl/mtg-engine/src/permanent.rs:261: pub fn apply_damage(&mut self, amount: u32) -> u32 {
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/permanent.rs-262- if amount == 0 {
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/permanent.rs-263- return 0;
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/permanent.rs-264- }
```
## Assistant
### Tool: Grep
**Args:**
```json
{
"-C": 50,
"output_mode": "content",
"path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/state.rs",
"pattern": "pub struct GameState"
}
```
## Assistant
**Result** (success):
```
1-// GameState — the complete game state snapshot.
2-//
3-// Ported from mage.game.GameState. The GameState struct holds everything
4-/ needed to describe a game in progress: players, zones, turn info, the
5-// stack, battlefield, exile, combat state, and continuous effects.
6-//
7-// The state is designed to be cheaply cloneable for AI search (minimax,
8-// MCTS). Use the `im` crate for persistent data structures in the future
9-// if clone performance becomes a bottleneck.
10-
11-use crate::abilities::AbilityStore;
12-use crate::constants::{PhaseStep, TurnPhase, Zone};
13-use crate::player::Player;
14-use crate::types::{ObjectId, PlayerId};
15-use crate::zones::{Battlefield, CardStore, Exile, Stack};
16-use serde::{Deserialize, Serialize};
17-use std::collections::HashMap;
18-
19-/// The complete game state at any point in time.
20-///
21-/// This is the "ground truth" that the game engine operates on. All game
22-/// actions modify a GameState, and the decision-making interfaces receive
23-/// a read-only reference to it (via GameView).
24-#[derive(Clone, Debug, Serialize, Deserialize)]
25:pub struct GameState {
26- // ── Players ──────────────────────────────────────────────────────────
27- /// All players, keyed by PlayerId. Each player owns their library,
28- /// hand, graveyard, mana pool, counters, and life total.
29- pub players: HashMap,
30-
31- /// Turn order (player IDs in APNAP order).
32- pub turn_order: Vec,
33-
34- // ── Shared zones ─────────────────────────────────────────────────────
35- /// The battlefield (all permanents in play).
36- pub battlefield: Battlefield,
37-
38- /// The stack (spells and abilities waiting to resolve).
39- pub stack: Stack,
40-
41- /// Exile zones.
42- pub exile: Exile,
43-
44- // ── Card store ───────────────────────────────────────────────────────
45- /// Central storage for all card data. Cards keep their CardData here
46- /// regardless of which zone they're in; zones only track ObjectIds.
47- pub card_store: CardStore,
48-
49- // ── Ability store ─────────────────────────────────────────────────
50- /// Central registry of all abilities currently in the game.
51- /// Abilities are registered when permanents enter the battlefield
52- /// and removed when they leave.
53- pub ability_store: AbilityStore,
54-
55- // ── Zone tracking ────────────────────────────────────────────────────
56- /// Tracks which zone each object is currently in.
57- /// Updated whenever an object changes zones.
58- pub object_zones: HashMap,
59-
60- // ── Turn state ───────────────────────────────────────────────────────
61- /// Current turn number (1-based).
62- pub turn_number: u32,
63-
64- /// Which player's turn it is.
65- pub active_player: PlayerId,
66-
67- /// Who currently has priority.
68- pub priority_player: PlayerId,
69-
70- /// Current turn phase.
71- pub current_phase: TurnPhase,
72-
73- /// Current step within the phase.
74- pub current_step: PhaseStep,
75-
```
## Assistant
### Tool: Read
**Args:**
```json
{
"file_path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/state.rs",
"limit": 60,
"offset": 75
}
```
## Assistant
**Result** (success):
```
75→
76→ // ── Game flags ───────────────────────────────────────────────────────
77→ /// Whether the game has ended.
78→ pub game_over: bool,
79→
80→ /// The winner (if any).
81→ pub winner: Option,
82→
83→ /// Whether we are currently resolving a spell/ability (re-entrancy guard).
84→ pub resolving: bool,
85→
86→ /// Counter for how many times all players have passed priority in
87→ /// succession (both pass = stack resolves or step ends).
88→ pub consecutive_passes: u32,
89→
90→ // ── Day/Night tracking (Innistrad mechanics) ─────────────────────────
91→ pub has_day_night: bool,
92→ pub is_daytime: bool,
93→
94→ // ── Monarch / Initiative ──────────────────────────────────────────────
95→ pub monarch: Option,
96→ pub initiative: Option,
97→
98→ // ── Values map (for tracking miscellaneous game state) ───────────────
99→ /// Generic key-value store for effects that need to track state across
100→ /// turns (e.g. "did a creature die this turn", "total damage dealt").
101→ pub values: HashMap,
102→}
103→
104→/// Describes where a specific game object currently exists.
105→#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
106→pub struct ZoneLocation {
107→ /// Which zone the object is in.
108→ pub zone: Zone,
109→ /// Which player controls/owns the zone (e.g. which player's hand).
110→ /// None for shared zones like the stack or battlefield.
111→ pub controller: Option,
112→}
113→
114→impl GameState {
115→ /// Create a new game state for the given players (in turn order).
116→ pub fn new(player_names: &[(&str, PlayerId)]) -> Self {
117→ let mut players = HashMap::new();
118→ let mut turn_order = Vec::new();
119→
120→ for &(name, id) in player_names {
121→ players.insert(id, Player::new(id, name));
122→ turn_order.push(id);
123→ }
124→
125→ let active = turn_order[0];
126→
127→ GameState {
128→ players,
129→ turn_order,
130→ battlefield: Battlefield::new(),
131→ stack: Stack::new(),
132→ exile: Exile::new(),
133→ card_store: CardStore::new(),
134→ ability_store: AbilityStore::new(),
```
## Assistant
## Assistant
Let me check how DealDamage is executed in game.rs, and also how the AI implementations handle select_attackers/select_blockers.
## Assistant
### Tool: Grep
**Args:**
```json
{
"-C": 30,
"output_mode": "content",
"path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/game.rs",
"pattern": "DealDamage \\{|Effect::DealDamage"
}
```
## Assistant
**Result** (success):
```
Output too large (20.7KB). Full output saved to: /mnt/dest-btrfs/home/jc/.claude/projects/-mnt-dest-btrfs-home-jc-src-mage/19ef5b00-b82b-4ba1-82e8-66c29187ed13/tool-results/toolu_019BBwsQ6vuW47NyedB63wfH.txt
Preview (first 2KB):
1075- } else {
1076- return false;
1077- }
1078- }
1079- Cost::Custom(_) => {
1080- / Custom costs: no-op (annotation only)
1081- }
1082- }
1083- }
1084- true
1085- }
1086-
1087- /// Execute a list of effects for a controller with given targets.
1088- pub fn execute_effects(&mut self, effects: &[Effect], controller: PlayerId, all_targets: &[ObjectId], source: Option) {
1089- // For compound fight/bite spells (e.g. [AddCounters, Bite]), pre-fight/bite
1090- // effects should only apply to the first target (your creature), matching
1091- // Java's per-effect target assignment where AddCountersTargetEffect targets
1092- // target 0 while DamageWithPowerFromOneToAnotherTargetEffect uses both.
1093- let has_fight_or_bite = effects.iter().any(|e| matches!(e, Effect::Fight | Effect::Bite));
1094-
1095- for effect in effects {
1096- let targets: &[ObjectId] = if has_fight_or_bite
1097- && !matches!(effect, Effect::Fight | Effect::Bite)
1098- && all_targets.len() >= 2
1099- {
1100- &all_targets[..1]
1101- } else {
1102- all_targets
1103- };
1104- match effect {
1105: Effect::DealDamage { amount } => {
1106- // Deal damage to target permanents.
1107- // Player targeting is handled separately via SelectedTargets.
1108- for &target_id in targets {
1109- if let Some(perm) = self.state.battlefield.get_mut(target_id) {
1110- perm.apply_damage(*amount);
1111- }
1112- }
1113- // If no permanent targets, deal damage to opponents
...
```
## Assistant
### Tool: Read
**Args:**
```json
{
"file_path": "/mnt/dest-btrfs/home/jc/.claude/projects/-mnt-dest-btrfs-home-jc-src-mage/19ef5b00-b82b-4ba1-82e8-66c29187ed13/tool-results/toolu_019BBwsQ6vuW47NyedB63wfH.txt",
"limit": 50,
"offset": 1
}
```
## Assistant
**Result** (success):
```
1→1075- } else {
2→1076- return false;
3→1077- }
4→1078- }
5→1079- Cost::Custom(_) => {
6→1080- / Custom costs: no-op (annotation only)
7→1081- }
8→1082- }
9→1083- }
10→1084- true
11→1085- }
12→1086-
13→1087- /// Execute a list of effects for a controller with given targets.
14→1088- pub fn execute_effects(&mut self, effects: &[Effect], controller: PlayerId, all_targets: &[ObjectId], source: Option) {
15→1089- // For compound fight/bite spells (e.g. [AddCounters, Bite]), pre-fight/bite
16→1090- // effects should only apply to the first target (your creature), matching
17→1091- // Java's per-effect target assignment where AddCountersTargetEffect targets
18→1092- // target 0 while DamageWithPowerFromOneToAnotherTargetEffect uses both.
19→1093- let has_fight_or_bite = effects.iter().any(|e| matches!(e, Effect::Fight | Effect::Bite));
20→1094-
21→1095- for effect in effects {
22→1096- let targets: &[ObjectId] = if has_fight_or_bite
23→1097- && !matches!(effect, Effect::Fight | Effect::Bite)
24→1098- && all_targets.len() >= 2
25→1099- {
26→1100- &all_targets[..1]
27→1101- } else {
28→1102- all_targets
29→1103- };
30→1104- match effect {
31→1105: Effect::DealDamage { amount } => {
32→1106- // Deal damage to target permanents.
33→1107- // Player targeting is handled separately via SelectedTargets.
34→1108- for &target_id in targets {
35→1109- if let Some(perm) = self.state.battlefield.get_mut(target_id) {
36→1110- perm.apply_damage(*amount);
37→1111- }
38→1112- }
39→1113- // If no permanent targets, deal damage to opponents
40→1114- // (simplified for "deal N damage to target opponent" effects)
41→1115- if targets.is_empty() {
42→1116- if let Some(opp_id) = self.state.opponent_of(controller) {
43→1117- if let Some(opp) = self.state.players.get_mut(&opp_id) {
44→1118- opp.life -= *amount as i32;
45→1119- }
46→1120- }
47→1121- }
48→1122- }
49→1123- Effect::Destroy => {
50→1124- for &target_id in targets {
```
## Assistant
Now let me check the AI implementations for select_attackers/select_blockers.
## Assistant
### Tool: Grep
**Args:**
```json
{
"-C": 15,
"output_mode": "content",
"path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/",
"pattern": "fn select_attackers|fn select_blockers"
}
```
## Assistant
**Result** (success):
```
Output too large (54.8KB). Full output saved to: /mnt/dest-btrfs/home/jc/.claude/projects/-mnt-dest-btrfs-home-jc-src-mage/19ef5b00-b82b-4ba1-82e8-66c29187ed13/tool-results/toolu_01A1t1WgwtaZQCNZ2mnByxdR.txt
Preview (first 2KB):
mtg-rl/mtg-ai/src/minimax_player.rs-328- game: &GameView<'_>,
mtg-rl/mtg-ai/src/minimax_player.rs-329- outcome: Outcome,
mtg-rl/mtg-ai/src/minimax_player.rs-330- message: &str,
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-331- ) -> bool {
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-332- self.heuristic.choose_use(game, outcome, message)
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-333- }
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-334-
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-335- fn choose_mode(
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-336- &mut self,
mtg-rl/mtg-ai/src/minimax_player.rs-337- game: &GameView<'_>,
mtg-rl/mtg-ai/src/minimax_player.rs-338- modes: &[NamedChoice],
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-339- ) -> usize {
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-340- self.heuristic.choose_mode(game, modes)
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-341- }
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-342-
mtg-rl/mtg-ai/src/minimax_player.rs:343: fn select_attackers(
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-344- &mut self,
mtg-rl/mtg-ai/src/minimax_player.rs-345- game: &GameView<'_>,
mtg-rl/mtg-ai/src/minimax_player.rs-346- possible_attackers: &[ObjectId],
mtg-rl/mtg-ai/src/minimax_player.rs-347- possible_defenders: &[ObjectId],
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-348- ) -> Vec<(ObjectId, ObjectId)> {
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-349- // In the full implementation, attacker selection would use search
...
```
## Assistant
Let me check the heuristic and random player implementations more efficiently.
## Assistant
### Tool: Grep
**Args:**
```json
{
"-C": 20,
"head_limit": 100,
"output_mode": "content",
"path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/",
"pattern": "fn select_attackers"
}
```
## Assistant
**Result** (success):
```
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-323- self.heuristic.choose_targets(game, outcome, requirement)
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-324- }
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-325-
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-326- fn choose_use(
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-327- &mut self,
mtg-rl/mtg-ai/src/minimax_player.rs-328- game: &GameView<'_>,
mtg-rl/mtg-ai/src/minimax_player.rs-329- outcome: Outcome,
mtg-rl/mtg-ai/src/minimax_player.rs-330- message: &str,
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-331- ) -> bool {
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-332- self.heuristic.choose_use(game, outcome, message)
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-333- }
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-334-
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-335- fn choose_mode(
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-336- &mut self,
mtg-rl/mtg-ai/src/minimax_player.rs-337- game: &GameView<'_>,
mtg-rl/mtg-ai/src/minimax_player.rs-338- modes: &[NamedChoice],
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-339- ) -> usize {
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-340- self.heuristic.choose_mode(game, modes)
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-341- }
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-342-
mtg-rl/mtg-ai/src/minimax_player.rs:343: fn select_attackers(
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-344- &mut self,
mtg-rl/mtg-ai/src/minimax_player.rs-345- game: &GameView<'_>,
mtg-rl/mtg-ai/src/minimax_player.rs-346- possible_attackers: &[ObjectId],
mtg-rl/mtg-ai/src/minimax_player.rs-347- possible_defenders: &[ObjectId],
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-348- ) -> Vec<(ObjectId, ObjectId)> {
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-349- // In the full implementation, attacker selection would use search
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-350- // to evaluate different attacker combinations. For now, use heuristic.
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-351- self.heuristic
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-352- .select_attackers(game, possible_attackers, possible_defenders)
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-353- }
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-354-
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-355- fn select_blockers(
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-356- &mut self,
mtg-rl/mtg-ai/src/minimax_player.rs-357- game: &GameView<'_>,
mtg-rl/mtg-ai/src/minimax_player.rs-358- attackers: &[AttackerInfo],
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-359- ) -> Vec<(ObjectId, ObjectId)> {
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-360- self.heuristic.select_blockers(game, attackers)
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-361- }
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-362-
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/minimax_player.rs-363- fn assign_damage(
--
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-82- self.pick_n(&requirement.legal_targets, count)
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-83- }
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-84-
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-85- fn choose_use(
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-86- &mut self,
mtg-rl/mtg-ai/src/random_player.rs-87- _game: &GameView<'_>,
mtg-rl/mtg-ai/src/random_player.rs-88- _outcome: Outcome,
mtg-rl/mtg-ai/src/random_player.rs-89- _message: &str,
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-90- ) -> bool {
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-91- self.rng.gen_bool(0.5)
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-92- }
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-93-
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-94- fn choose_mode(
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-95- &mut self,
mtg-rl/mtg-ai/src/random_player.rs-96- _game: &GameView<'_>,
mtg-rl/mtg-ai/src/random_player.rs-97- modes: &[NamedChoice],
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-98- ) -> usize {
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-99- self.pick(modes).index
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-100- }
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-101-
mtg-rl/mtg-ai/src/random_player.rs:102: fn select_attackers(
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-103- &mut self,
mtg-rl/mtg-ai/src/random_player.rs-104- _game: &GameView<'_>,
mtg-rl/mtg-ai/src/random_player.rs-105- possible_attackers: &[ObjectId],
mtg-rl/mtg-ai/src/random_player.rs-106- possible_defenders: &[ObjectId],
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-107- ) -> Vec<(ObjectId, ObjectId)> {
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-108- if possible_attackers.is_empty() || possible_defenders.is_empty() {
mtg-rl/mtg-ai/src/random_player.rs-109- return Vec::new();
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-110- }
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-111- // Randomly decide how many creatures to attack with (0 to all).
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-112- let count = self.rng.gen_range(0..=possible_attackers.len());
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-113- let attackers = self.pick_n(possible_attackers, count);
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-114- // Each attacker attacks a random defender.
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-115- attackers
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-116- .into_iter()
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-117- .map(|a| {
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-118- let d = *self.pick(possible_defenders);
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-119- (a, d)
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-120- })
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-121- .collect()
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/random_player.rs-122- }
--
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/heuristic_player.rs-129- &mut self,
mtg-rl/mtg-ai/src/heuristic_player.rs-130- _game: &GameView<'_>,
mtg-rl/mtg-ai/src/heuristic_player.rs-131- outcome: Outcome,
mtg-rl/mtg-ai/src/heuristic_player.rs-132- _message: &str,
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/heuristic_player.rs-133- ) -> bool {
mtg-rl/mtg-ai/src/heuristic_player.rs-134- / Port of ComputerPlayer.chooseUse:
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/heuristic_player.rs-135- // "Be proactive! Always use abilities, the evaluation function will
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/heuristic_player.rs-136- // decide if it's good or not." Say yes to everything except AIDontUseIt.
mtg-rl/mtg-ai/src/heuristic_player.rs-137- outcome != Outcome::AIDontUseIt
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/heuristic_player.rs-138- }
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/heuristic_player.rs-139-
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/heuristic_player.rs-140- fn choose_mode(
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/heuristic_player.rs-141- &mut self,
mtg-rl/mtg-ai/src/heuristic_player.rs-142- _game: &GameView<'_>,
mtg-rl/mtg-ai/src/heuristic_player.rs-143- modes: &[NamedChoice],
/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-ai/src/heuristic_player.rs-144- ) -> usize {
[Showing results with pagination = limit: 100, offset: 0]
```
## Assistant
## Assistant
Let me also check how `AlwaysPassPlayer` handles these methods, and the Permanent methods for tapping/attacking.
## Assistant
### Tool: Grep
**Args:**
```json
{
"output_mode": "files_with_matches",
"path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/",
"pattern": "AlwaysPassPlayer|struct.*AlwaysPass"
}
```
## Assistant
**Result** (success):
```
Found 1 file
mtg-rl/mtg-engine/src/game.rs
```
## Assistant
### Tool: Grep
**Args:**
```json
{
"-C": 5,
"output_mode": "content",
"path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/permanent.rs",
"pattern": "fn can_attack|fn can_block|fn tap\\b|fn untap\\b|fn has_vigilance|fn has_lifelink|pub summoning_sick"
}
```
## Assistant
**Result** (success):
```
16- pub controller: PlayerId,
17- /// Whether the permanent is tapped.
18- pub tapped: bool,
19- /// Whether the permanent has summoning sickness.
20- /// Creatures with summoning sickness cannot attack or use {T} abilities.
21: pub summoning_sick: bool,
22- /// Damage currently marked on this permanent (creatures only).
23- pub damage: u32,
24- /// Counters on this permanent (+1/+1, loyalty, etc.).
25- pub counters: Counters,
26- /// If this permanent is attached to another (e.g. Aura, Equipment).
--
149-
150- pub fn has_reach(&self) -> bool {
151- self.has_keyword(KeywordAbilities::REACH)
152- }
153-
154: pub fn has_vigilance(&self) -> bool {
155- self.has_keyword(KeywordAbilities::VIGILANCE)
156- }
157-
158- pub fn has_first_strike(&self) -> bool {
159- self.has_keyword(KeywordAbilities::FIRST_STRIKE)
--
165-
166- pub fn has_trample(&self) -> bool {
167- self.has_keyword(KeywordAbilities::TRAMPLE)
168- }
169-
170: pub fn has_lifelink(&self) -> bool {
171- self.has_keyword(KeywordAbilities::LIFELINK)
172- }
173-
174- pub fn has_deathtouch(&self) -> bool {
175- self.has_keyword(KeywordAbilities::DEATHTOUCH)
--
218- }
219-
220- // ── Tap/Untap ──────────────────────────────────────────────────────
221-
222- /// Tap this permanent. Returns true if it was untapped (state changed).
223: pub fn tap(&mut self) -> bool {
224- if !self.tapped {
225- self.tapped = true;
226- true
227- } else {
228- false
229- }
230- }
231-
232- /// Untap this permanent. Returns true if it was tapped (state changed).
233: pub fn untap(&mut self) -> bool {
234- if self.tapped {
235- self.tapped = false;
236- true
237- } else {
238- false
--
241-
242- // ── Combat ─────────────────────────────────────────────────────────
243-
244- /// Whether this creature can attack (not tapped, no summoning sickness
245- /// unless it has haste, and not a defender).
246: pub fn can_attack(&self) -> bool {
247- self.is_creature()
248- && !self.tapped
249- && !self.has_defender()
250- && (!self.summoning_sick || self.has_haste())
251- }
252-
253- /// Whether this creature can block.
254: pub fn can_block(&self) -> bool {
255- self.is_creature() && !self.tapped
256- }
257-
258- // ── Damage ─────────────────────────────────────────────────────────
259-
```
## Assistant
Now let me find the `AlwaysPassPlayer` in game.rs and understand how the test player works.
## Assistant
### Tool: Grep
**Args:**
```json
{
"-C": 3,
"output_mode": "content",
"path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/game.rs",
"pattern": "AlwaysPassPlayer\""
}
```
## Assistant
**Result** (success):
```
No matches found
```
## Assistant
### Tool: Grep
**Args:**
```json
{
"-C": 80,
"output_mode": "content",
"path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/game.rs",
"pattern": "struct AlwaysPassPlayer|impl.*PlayerDecisionMaker.*for.*AlwaysPass"
}
```
## Assistant
**Result** (success):
```
2248- fn resolve_fight_pair(
2249- state: &GameState,
2250- targets: &[ObjectId],
2251- source: Option,
2252- controller: PlayerId,
2253- ) -> (Option, Option) {
2254- / Two explicit targets from TargetSpec::Pair selection:
2255- // targets[0] = creature you control, targets[1] = creature opponent controls
2256- if targets.len() >= 2 {
2257- let t0 = state.battlefield.get(targets[0]).map(|_| targets[0]);
2258- let t1 = state.battlefield.get(targets[1]).map(|_| targets[1]);
2259- if t0.is_some() && t1.is_some() {
2260- return (t0, t1);
2261- }
2262- }
2263-
2264- / Single target + source creature (ETB triggers like Affectionate Indrik):
2265- // source = the creature, targets[0] = opponent's creature
2266- if targets.len() == 1 {
2267- if let Some(sid) = source {
2268- if state.battlefield.get(sid).map_or(false, |p| p.is_creature()) {
2269- let tid = state.battlefield.get(targets[0]).map(|_| targets[0]);
2270- return (Some(sid), tid);
2271- }
2272- }
2273- }
2274-
2275- / Fallback: auto-select strongest creatures on each side
2276- let fighter = state
2277- .battlefield
2278- .iter()
2279- .filter(|p| p.controller == controller && p.is_creature())
2280- .max_by_key(|p| p.power())
2281- .map(|p| p.id());
2282- let target = state
2283- .battlefield
2284- .iter()
2285- .filter(|p| p.controller != controller && p.is_creature())
2286- .max_by_key(|p| p.power())
2287- .map(|p| p.id());
2288- (fighter, target)
2289- }
2290-
2291- /// Check if the game should end and return a result if so.
2292- fn check_game_end(&self) -> Option {
2293- if !self.state.should_end() {
2294- return None;
2295- }
2296-
2297- let alive = self.state.active_players();
2298-
2299- let (winner, reason) = if alive.len() == 1 {
2300- (Some(alive[0]), GameEndReason::LastPlayerStanding)
2301- } else if alive.is_empty() {
2302- (None, GameEndReason::Draw)
2303- } else {
2304- return None;
2305- };
2306-
2307- Some(GameResult {
2308- winner,
2309- turn_number: self.turn_manager.turn_number,
2310- reason,
2311- })
2312- }
2313-}
2314-
2315-#[cfg(test)]
2316-mod tests {
2317- use super::*;
2318- use crate::abilities::{Ability, Cost, Effect, TargetSpec};
2319- use crate::card::CardData;
2320- use crate::constants::{CardType, KeywordAbilities, Outcome, SubType};
2321- use crate::decision::{
2322- AttackerInfo, DamageAssignment, GameView, NamedChoice, PlayerAction,
2323- ReplacementEffectChoice, TargetRequirement, UnpaidMana,
2324- };
2325- use crate::mana::Mana;
2326-
2327- /// A minimal decision maker that always passes priority.
2328: struct AlwaysPassPlayer;
2329-
2330: impl PlayerDecisionMaker for AlwaysPassPlayer {
2331- fn priority(&mut self, _game: &GameView<'_>, _legal: &[PlayerAction]) -> PlayerAction {
2332- PlayerAction::Pass
2333- }
2334- fn choose_targets(&mut self, _: &GameView<'_>, _: Outcome, _: &TargetRequirement) -> Vec { vec![] }
2335- fn choose_use(&mut self, _: &GameView<'_>, _: Outcome, _: &str) -> bool { false }
2336- fn choose_mode(&mut self, _: &GameView<'_>, _: &[NamedChoice]) -> usize { 0 }
2337- fn select_attackers(&mut self, _: &GameView<'_>, _: &[ObjectId], _: &[ObjectId]) -> Vec<(ObjectId, ObjectId)> { vec![] }
2338- fn select_blockers(&mut self, _: &GameView<'_>, _: &[AttackerInfo]) -> Vec<(ObjectId, ObjectId)> { vec![] }
2339- fn assign_damage(&mut self, _: &GameView<'_>, _: &DamageAssignment) -> Vec<(ObjectId, u32)> { vec![] }
2340- fn choose_mulligan(&mut self, _: &GameView<'_>, _: &[ObjectId]) -> bool { false }
2341- fn choose_cards_to_put_back(&mut self, _: &GameView<'_>, _: &[ObjectId], _: usize) -> Vec { vec![] }
2342- fn choose_discard(&mut self, _: &GameView<'_>, _: &[ObjectId], _: usize) -> Vec { vec![] }
2343- fn choose_amount(&mut self, _: &GameView<'_>, _: &str, min: u32, _: u32) -> u32 { min }
2344- fn choose_mana_payment(&mut self, _: &GameView<'_>, _: &UnpaidMana, _: &[PlayerAction]) -> Option { None }
2345- fn choose_replacement_effect(&mut self, _: &GameView<'_>, _: &[ReplacementEffectChoice]) -> usize { 0 }
2346- fn choose_pile(&mut self, _: &GameView<'_>, _: Outcome, _: &str, _: &[ObjectId], _: &[ObjectId]) -> bool { true }
2347- fn choose_option(&mut self, _: &GameView<'_>, _: Outcome, _: &str, _: &[NamedChoice]) -> usize { 0 }
2348- }
2349-
2350- fn make_basic_land(name: &str, owner: PlayerId) -> CardData {
2351- let mut card = CardData::new(ObjectId::new(), owner, name);
2352- card.card_types = vec![CardType::Land];
2353- card
2354- }
2355-
2356- fn make_creature(name: &str, owner: PlayerId, power: i32, toughness: i32) -> CardData {
2357- let mut card = CardData::new(ObjectId::new(), owner, name);
2358- card.card_types = vec![CardType::Creature];
2359- card.power = Some(power);
2360- card.toughness = Some(toughness);
2361- card.keywords = KeywordAbilities::empty();
2362- card
2363- }
2364-
2365- fn make_deck(owner: PlayerId) -> Vec {
2366- let mut deck = Vec::new();
2367- // 20 lands
2368- for _ in 0..20 {
2369- deck.push(make_basic_land("Forest", owner));
2370- }
2371- // 20 creatures
2372- for _ in 0..20 {
2373- deck.push(make_creature("Grizzly Bears", owner, 2, 2));
2374- }
2375- deck
2376- }
2377-
2378- #[test]
2379- fn game_creation() {
2380- let p1 = PlayerId::new();
2381- let p2 = PlayerId::new();
2382-
2383- let config = GameConfig {
2384- players: vec![
2385- PlayerConfig { name: "Alice".to_string(), deck: make_deck(p1) },
2386- PlayerConfig { name: "Bob".to_string(), deck: make_deck(p2) },
2387- ],
2388- starting_life: 20,
2389- };
2390-
2391- let game = Game::new_two_player(
2392- config,
2393- vec![
2394- (p1, Box::new(AlwaysPassPlayer)),
2395- (p2, Box::new(AlwaysPassPlayer)),
2396- ],
2397- );
2398-
2399- assert_eq!(game.state.players.len(), 2);
2400- assert_eq!(game.state.player(p1).unwrap().life, 20);
2401- assert_eq!(game.state.player(p2).unwrap().life, 20);
2402- // Each player should have 40 cards in library
2403- assert_eq!(game.state.player(p1).unwrap().library.len(), 40);
2404- assert_eq!(game.state.player(p2).unwrap().library.len(), 40);
2405- }
2406-
2407- #[test]
2408- fn game_runs_to_completion() {
2409- let p1 = PlayerId::new();
2410- let p2 = PlayerId::new();
--
3942-
3943- // Add 3 cards to graveyard
3944- let gy1 = ObjectId::new();
3945- let gy2 = ObjectId::new();
3946- let gy3 = ObjectId::new();
3947- game.state.players.get_mut(&p1).unwrap().graveyard.add(gy1);
3948- game.state.players.get_mut(&p1).unwrap().graveyard.add(gy2);
3949- game.state.players.get_mut(&p1).unwrap().graveyard.add(gy3);
3950-
3951- // Can't exile 4 (only 3)
3952- assert!(!game.pay_costs(p1, source_id, &[Cost::ExileFromGraveyard(4)]));
3953-
3954- // Exile 2
3955- assert!(game.pay_costs(p1, source_id, &[Cost::ExileFromGraveyard(2)]));
3956- assert_eq!(game.state.players.get(&p1).unwrap().graveyard.len(), 1);
3957- // Exiled cards should be in exile zone
3958- assert!(game.state.exile.contains(gy3) || game.state.exile.contains(gy2));
3959- }
3960-
3961- #[test]
3962- fn pay_exile_from_hand_cost() {
3963- let (mut game, p1, _p2) = setup_game();
3964- let source_id = add_creature(&mut game, p1, "Source");
3965-
3966- // Add 2 cards to hand
3967- let h1 = ObjectId::new();
3968- let h2 = ObjectId::new();
3969- game.state.players.get_mut(&p1).unwrap().hand.add(h1);
3970- game.state.players.get_mut(&p1).unwrap().hand.add(h2);
3971- let before = game.state.players.get(&p1).unwrap().hand.len();
3972-
3973- // Exile 1
3974- assert!(game.pay_costs(p1, source_id, &[Cost::ExileFromHand(1)]));
3975- assert_eq!(game.state.players.get(&p1).unwrap().hand.len(), before - 1);
3976- }
3977-
3978- #[test]
3979- fn pay_sacrifice_other_cost() {
3980- let (mut game, p1, _p2) = setup_game();
3981- let source_id = add_creature(&mut game, p1, "Source");
3982- let other_id = add_creature(&mut game, p1, "Other Creature");
3983-
3984- // Sacrifice another creature
3985- assert!(game.pay_costs(p1, source_id, &[Cost::SacrificeOther("a creature".into())]));
3986- // The other creature should be gone
3987- assert!(!game.state.battlefield.contains(other_id));
3988- // Source should still be there
3989- assert!(game.state.battlefield.contains(source_id));
3990- }
3991-
3992- #[test]
3993- fn pay_untap_self_cost() {
3994- let (mut game, p1, _p2) = setup_game();
3995- let source_id = add_creature(&mut game, p1, "Untap Me");
3996-
3997- // Can't untap (not tapped)
3998- assert!(!game.pay_costs(p1, source_id, &[Cost::UntapSelf]));
3999-
4000- // Tap it first
4001- game.state.battlefield.get_mut(source_id).unwrap().tap();
4002- assert!(game.state.battlefield.get(source_id).unwrap().tapped);
4003-
4004- // Now untap cost works
4005- assert!(game.pay_costs(p1, source_id, &[Cost::UntapSelf]));
4006- assert!(!game.state.battlefield.get(source_id).unwrap().tapped);
4007- }
4008-}
4009-
4010-#[cfg(test)]
4011-mod vivid_tests {
4012- use super::*;
4013- use crate::abilities::Effect;
4014- use crate::card::CardData;
4015- use crate::constants::{CardType, KeywordAbilities, Outcome};
4016- use crate::decision::*;
4017- use crate::game::{GameConfig, PlayerConfig};
4018- use crate::mana::{ManaCost};
4019- use crate::permanent::Permanent;
4020- use crate::types::{ObjectId, PlayerId};
4021-
4022: struct AlwaysPassPlayer;
4023: impl PlayerDecisionMaker for AlwaysPassPlayer {
4024- fn priority(&mut self, _: &GameView<'_>, _: &[PlayerAction]) -> PlayerAction { PlayerAction::Pass }
4025- fn choose_targets(&mut self, _: &GameView<'_>, _: Outcome, _: &TargetRequirement) -> Vec { vec![] }
4026- fn choose_use(&mut self, _: &GameView<'_>, _: Outcome, _: &str) -> bool { false }
4027- fn choose_mode(&mut self, _: &GameView<'_>, _: &[NamedChoice]) -> usize { 0 }
4028- fn select_attackers(&mut self, _: &GameView<'_>, _: &[ObjectId], _: &[ObjectId]) -> Vec<(ObjectId, ObjectId)> { vec![] }
4029- fn select_blockers(&mut self, _: &GameView<'_>, _: &[AttackerInfo]) -> Vec<(ObjectId, ObjectId)> { vec![] }
4030- fn assign_damage(&mut self, _: &GameView<'_>, _: &DamageAssignment) -> Vec<(ObjectId, u32)> { vec![] }
4031- fn choose_mulligan(&mut self, _: &GameView<'_>, _: &[ObjectId]) -> bool { false }
4032- fn choose_cards_to_put_back(&mut self, _: &GameView<'_>, _: &[ObjectId], _: usize) -> Vec { vec![] }
4033- fn choose_discard(&mut self, _: &GameView<'_>, _: &[ObjectId], _: usize) -> Vec { vec![] }
4034- fn choose_amount(&mut self, _: &GameView<'_>, _: &str, min: u32, _: u32) -> u32 { min }
4035- fn choose_mana_payment(&mut self, _: &GameView<'_>, _: &UnpaidMana, _: &[PlayerAction]) -> Option { None }
4036- fn choose_replacement_effect(&mut self, _: &GameView<'_>, _: &[ReplacementEffectChoice]) -> usize { 0 }
4037- fn choose_pile(&mut self, _: &GameView<'_>, _: Outcome, _: &str, _: &[ObjectId], _: &[ObjectId]) -> bool { true }
4038- fn choose_option(&mut self, _: &GameView<'_>, _: Outcome, _: &str, _: &[NamedChoice]) -> usize { 0 }
4039- }
4040-
4041- fn make_deck(owner: PlayerId) -> Vec {
4042- (0..20).map(|i| {
4043- let mut c = CardData::new(ObjectId::new(), owner, &format!("Card {i}"));
4044- c.card_types = vec![CardType::Land];
4045- c
4046- }).collect()
4047- }
4048-
4049- fn setup() -> (Game, PlayerId, PlayerId) {
4050- let p1 = PlayerId::new();
4051- let p2 = PlayerId::new();
4052- let config = GameConfig {
4053- players: vec![
4054- PlayerConfig { name: "A".into(), deck: make_deck(p1) },
4055- PlayerConfig { name: "B".into(), deck: make_deck(p2) },
4056- ],
4057- starting_life: 20,
4058- };
4059- let game = Game::new_two_player(config, vec![
4060- (p1, Box::new(AlwaysPassPlayer)),
4061- (p2, Box::new(AlwaysPassPlayer)),
4062- ]);
4063- (game, p1, p2)
4064- }
4065-
4066- fn add_colored_creature(game: &mut Game, owner: PlayerId, name: &str, mana: &str) -> ObjectId {
4067- let id = ObjectId::new();
4068- let mut card = CardData::new(id, owner, name);
4069- card.card_types = vec![CardType::Creature];
4070- card.mana_cost = ManaCost::parse(mana);
4071- card.power = Some(2);
4072- card.toughness = Some(2);
4073- card.keywords = KeywordAbilities::empty();
4074- game.state.battlefield.add(Permanent::new(card, owner));
4075- id
4076- }
4077-
4078- #[test]
4079- fn count_colors_zero_for_colorless() {
4080- let (game, p1, _) = setup();
4081- // Only lands (colorless) on battlefield
4082- assert_eq!(game.count_colors_among_permanents(p1), 0);
4083- }
4084-
4085- #[test]
4086- fn count_colors_counts_distinct() {
4087- let (mut game, p1, _) = setup();
4088- // Add a red creature
4089- add_colored_creature(&mut game, p1, "Goblin", "{R}");
4090- assert_eq!(game.count_colors_among_permanents(p1), 1);
4091-
4092- // Add another red creature (still 1 color)
4093- add_colored_creature(&mut game, p1, "Goblin 2", "{1}{R}");
4094- assert_eq!(game.count_colors_among_permanents(p1), 1);
4095-
4096- // Add a green creature (now 2 colors)
4097- add_colored_creature(&mut game, p1, "Elf", "{G}");
4098- assert_eq!(game.count_colors_among_permanents(p1), 2);
4099-
4100- // Add a multicolor creature (adds blue and white)
4101- add_colored_creature(&mut game, p1, "Angel", "{W}{U}");
4102- assert_eq!(game.count_colors_among_permanents(p1), 4);
4103- }
```
## Assistant
I now have a thorough understanding of the codebase. Let me also check the `opponent_of()` method to understand how to get the defending player.
## Assistant
### Tool: Grep
**Args:**
```json
{
"-C": 10,
"output_mode": "content",
"path": "/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/state.rs",
"pattern": "fn opponent_of|fn next_player|fn active_players|fn should_end"
}
```
## User
[Request interrupted by user]