<task-notification> <task-id>aa5f9b3</task-id> <status>completed</status> <summary>Agent "Check keyword enforcement in Rust" completed</summary> <result>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

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)</result>
  <usage>total_tokens: 72014
  tool_uses: 24
  duration_ms: 63618</usage> </task-notification>

Full transcript available at: /tmp/claude-1000/-mnt-dest-btrfs-home-jc-src-mage/tasks/aa5f9b3.output

<task-notification> <task-id>ac21389</task-id> <status>completed</status> <summary>Agent "Explore Rust engine capabilities" completed</summary> <result>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<Color> 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<CombatGroup> (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<TargetEntry> — 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<KeywordAbilities>
• 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<CounterType, u32> (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<i32>)
• keywords (KeywordAbilities bitflags)
• abilities (Vec<Ability>)
• 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<AbilityId, Ability> (all abilities)
• HashMap<ObjectId, Vec<AbilityId>> (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

---

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.</result>
<usage>total_tokens: 114137
tool_uses: 25
duration_ms: 114113</usage>
</task-notification>
Full transcript available at: /tmp/claude-1000/-mnt-dest-btrfs-home-jc-src-mage/tasks/ac21389.output

<task-notification> <task-id>a715424</task-id> <status>completed</status> <summary>Agent "Catalog Custom effects in card sets" completed</summary> <result>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

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

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:

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<Effect> }

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.</result>
<usage>total_tokens: 62447
tool_uses: 18
duration_ms: 98767</usage>
</task-notification>
Full transcript available at: /tmp/claude-1000/-mnt-dest-btrfs-home-jc-src-mage/tasks/a715424.output

<task-notification> <task-id>a2b068c</task-id> <status>completed</status> <summary>Agent "Explore Java engine capabilities" completed</summary> <result>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<MageObjectReference> 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)</result>
  <usage>total_tokens: 77883
  tool_uses: 53
  duration_ms: 121005</usage> </task-notification>

Full transcript available at: /tmp/claude-1000/-mnt-dest-btrfs-home-jc-src-mage/tasks/a2b068c.output

Ralph Loop Command

Execute the setup script to initialize the Ralph loop:

🔄 Ralph loop activated in this session!

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

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

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

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

🔄

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

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

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

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

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

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

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

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