Public

Identify and Fix Rust Engine Gaps vs JavaPublic

The user aimed to compare their Rust game engine with a Java engine to find missing features that prevent correct gameplay for four card sets. After thorough analysis, they identified major gaps like missing combat integration and incomplete triggered abilities. They updated the project roadmap with these deficiencies and began planning step-by-step improvements to achieve feature parity, focusing first on integrating combat into the Rust engine's game loop.

Agent

Claude Code

Model

Claude Opus 4.6

Shared

Feb 15, 2:56 PM

Messages118

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.

I'll start by thoroughly exploring both engines in parallel to identify gaps.

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.

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.

All four agents are still working. I'll wait for them to complete before synthesizing findings.

<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

HASTE - Enforced
- Used in can_attack() (permanent.rs:250) to bypass summoning sickness
- Granted during GainControlUntilEndOfTurn effect (game.rs:1727)
FLYING - Enforced
- Used in can_block() check (combat.rs:205): flyers can only be blocked by flying or reach creatures
REACH - Enforced
- Used in can_block() check (combat.rs:205): reach creatures can block flyers
DEFENDER - Enforced
- Used in can_attack() check (permanent.rs:249): creatures with defender cannot attack
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)
TRAMPLE - Enforced
- Excess damage from trampler assigned to defending player when blockers are destroyed (combat.rs:296-298)
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)
MENACE - Enforced
- Checked via satisfies_menace() function (combat.rs:216-224)
- Requires 2+ blockers if blocked at all
INDESTRUCTIBLE - Enforced
- Checked in state-based action for lethal damage (state.rs:296)
- Creatures with indestructible survive lethal damage

Keywords with Partial/Limited Support

VIGILANCE - NOT Enforced
- No code path prevents tapping when attacking
- Combat phase is not implemented in the game loop
LIFELINK - NOT Enforced
- No code connects lifelink to damage → life gain
- Damage is applied directly to creatures/players with no lifelink check
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:

Rule 704.5a - Player at 0 or less life loses (state.rs:280-282)
Rule 704.5c - Player with 10+ poison counters loses (state.rs:285-287)
Rule 704.5f - Creature with 0 or less toughness goes to graveyard (state.rs:294-295)
Rule 704.5g - Creature with lethal damage marked on it is destroyed (if not indestructible) (state.rs:296-297)
Rule 704.5j - Planeswalker with 0 or less loyalty goes to graveyard (state.rs:305-308)
Rule 704.5k - Legend rule - legendary permanents with same name (state.rs:312-338)
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)</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

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.

<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):

Untap — Untap permanents, clear mana pools
Upkeep — Beginning-of-upkeep triggers
Draw — Active player draws a card
PrecombatMain — First main phase (land play, spells, abilities)
BeginCombat → DeclareAttackers → DeclareBlockers → FirstStrikeDamage → CombatDamage → EndCombat (combat phase)
PostcombatMain — Second main phase
EndStep → Cleanup — End of turn cleanup

GAME LOOP FLOW (process_step):

Turn-based actions: Untap, draw, cleanup (automatic)
State-based actions: Creatures with 0 toughness die; players with ≤0 life lose; loop until none found
Triggered abilities: Queued on stack (TODO: not yet fully implemented)
Priority loop: Players gain priority, can cast spells/activate abilities, pass until all pass or stack resolves
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:

Library — Ordered deck (top = index 0); peek/draw/shuffle; put_on_top/bottom
Hand — Unordered cards; 7-card max size (enforced in cleanup)
Battlefield — Contains Permanent structs, not just IDs; indexed by ObjectId
Graveyard — Unordered cards; public info zone
Exile — Unordered cards; public info zone
Stack — StackItem entries (spells with controller); LIFO resolution
Command — For commanders/conspiracies (declared but not fully used)
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):

Copy effects
Control-changing
Text-changing
Type-changing
Color-changing
Ability-adding/removing
Power/toughness (7 sub-layers: CDA, Set, Modify, Counters, Switch)
Player effects
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:

Triggered abilities on stack (task #13) — Events are queued but abilities not yet put on stack
Combat tricks during declare — Can't respond between declare attackers and blockers
Replacement effect integration — Declared but not hooked into event flow
State-based action loop — Simplified; doesn't handle all MTG rules

From code review:

Hybrid mana — Not modeled (would need {B/R} syntax support)
Restricted mana — "Spend only on creatures" not tracked
Evoke enforcement — Declared in StaticEffect but not enforced
Ward enforcement — No cost-paying system for ward taxes
Flashback/Escape — Cost types declared but not enforced
Copy effects — Layer 1 defined but no copy() for permanents
Protection — Listed as keyword but no enforcement
Landwalk evasion — Keywords declared but not checked in combat validation
Shroud/Hexproof — Not enforced for targeting (all targets are valid)
Convoke/Delve/Cascade — Keywords declared but no logic
Storm/Storm effects — Not implemented
Mulligan variants — Only London mulligan; no Traditional/Modern
Choice between multiple decisions — No multi-step targeting (e.g., "target creature, then target opponent")

ARCHITECTURE STRENGTHS

Data-oriented design — Effects, costs, and abilities as enums with match arms (no inheritance)
Serde serialization — All core types implement Serialize/Deserialize for save/load
Send + Sync everywhere — Types verified at compile time for parallelism
Layered organization — Clear separation: game loop (game.rs) → effects (effects.rs) → abilities (abilities.rs)
Filter system — String-based filters (simple but extensible)
Event logging — Events tracked for triggered ability evaluation
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.</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

Good, the Rust engine inventory is complete. Two agents done, two still running. Let me check on the remaining two.

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.

<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

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

90x "Static effect" — Placeholder for complex static effects across all sets
79x "ETB effect" — Cards that trigger on enter the battlefield
67x "Activated effect" — Cards with activated abilities needing proper implementation
21x "Spell effect" — Generic spell mechanics
21x "Attack trigger" — Combat-related triggers
14x "Spell cast trigger" — Casting-related mechanics
11x "Attach to target creature you control" — Aura/Equipment attachment
11x "Dies effect" — Death triggers
6x "Saga mechanics" — Enchantment Saga cards
4x "Return exiled card to hand" — Exile recursion mechanics
3x "Tapped trigger" — Tapped-creature mechanics
3x "Cast from graveyard, then exile" — Flashback/exile mechanics
3x "Cast from graveyard" — Pure graveyard casting
2x "Each opponent loses 1 life" — Opponent life loss
2x "Creatures you control gain trample" — Evasion grants
2x "Draw second card trigger" — Card draw triggers
2x "Enchant creature" — Aura enchantment
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)

Proper ETB Effect Framework (122 customs)
- Current: 79 generic "ETB effect" stubs
- Need: Effect::EntersBattlefield { effect: Box<Effect> }
Modal Spells / Choice Mechanics (20+ customs)
- Modes like "Choose one:" or "Choose two:"
- Affects FDN heavily
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)

Combat Trigger Framework (45 customs)
- Attack triggers, combat phase effects
- Includes raid, exalted, etc.
Conditional/State-Based Effects (30+ customs)
- "Power = X", "Cost reduction if condition"
- "+X/+X where X = [game state]"
Graveyard Casting & Exile Management (25 customs)
- Flashback, Escape, Suspend mechanics
- "Exile top card, play until next end step"
Spell/Cast Triggers (47 customs)
- Cost reduction for casting
- Triggers when spells are cast
Copy & Token Creation (20+ customs)
- "Create a token copy of target creature"
- "Copy this spell"

MEDIUM (Would eliminate 10-20 customs each)

Saga Mechanics (6 customs)
- Enchantment subtypes with lore counters
- All TLA/TDM exclusive
Die/Sacrifice Triggers (18 customs)
- Morbid, aristocrat mechanics
Aura/Equipment Attachment (28 customs)
- Proper enchant target binding
Keyword Ability Grants (15+ customs)
- "Grant [keyword] until end of turn"
- Conditional flash, haste, etc.

LOWER (Single-digit impact each but notable)

Delve/Convoke/Affinity (4 customs)
- Set-specific keywords as static effects
Ward/Tax Effects (2 customs)
- Ward keyword, tax mechanics
Transform Mechanics (3 customs)
- Double-faced card behavior
Trigger Multipliers (1 custom)
- "Other [type] triggers an additional time"
X-Cost Effects (Several)
- Distribute counters, X-based P/T, etc.
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

Good, three agents done. Let me wait for the Java engine exploration to complete.

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.

Let me verify one critical claim from the keyword agent - whether combat is actually missing from the game loop.

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.

The ROADMAP.md has been rewritten. Here's a summary of the key findings from comparing the two engines:

Critical gaps (affect ALL cards):

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).
Triggered abilities never stack — Events are emitted but abilities don't fire. ETB, attack, death, upkeep triggers are all silent (~400+ cards).
Continuous effect layers never applied — 7-layer system defined but never runs. Lord effects, anthems, keyword grants are all decorative (~50+ cards).
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.

<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:

OneShotEffect - One-time effects that resolve immediately
- apply() method executes effect once
- Examples: DealDamageTargetEffect, DestroyTargetEffect, DrawCardsEqualsEffect
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
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):

Copy (Layer.CopyEffects_1) - Copy effects determine what a permanent looks like
Control (Layer.ControlChangingEffects_2) - Control-changing effects
Text (Layer.TextChangingEffects_3) - Text-modifying effects
Type (Layer.TypeChangingEffects_4) - Type/subtype-changing effects
Color (Layer.ColorChangingEffects_5) - Color-changing effects
Ability (Layer.AbilityAddingRemovingEffects_6) - Grant/remove abilities
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:

Event is about to happen (e.g., creature entering battlefield)
getReplacementEffects() list is checked
checksEventType() filters for relevant events
applies() checks source-specific conditions
replaceEvent() modifies or cancels event
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):

Evasion/Combat Keywords:
- Flying, Menace, Shadow, etc. → EvasionAbility with RestrictionEffect to prevent blocking
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)
Special Keywords:
- Banding, bands with other → tracked via bandedCards list
- Goad → goadingPlayers set on permanent, forces attacks
- Phasing → phasedIn flag on permanent
Cost/Ability Keywords:
- Equip, Entwine, Buyback → Cost modifications
- Flashback, Evoke, Prowess → TriggeredAbility
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:

Effect layer system - All 7 layers in correct order
Replacement effect scope - Proper battlefield checks (614.12)
Continuous effect duration - EOT, EOCombat, permanent, etc.
Watcher system - Event-driven state tracking for triggers
Combat mechanics - Evasion, first strike, trample, blocking constraints
Loyalty - Planeswalker activation tracking per-turn
Equipment/Aura attachment - Replacement on zone change, fall-off detection
X-cost announcements - Variable mana before payment
Modal spells - Mode selection and independent resolution
Copy effects - Both spell and permanent copying with attribute inheritance
Trigger delays - Triggered abilities queued until priority (603.3)
All 600+ event types - Especially zone change, damage, combat variants
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

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.

Ralph Loop Command

Execute the setup script to initialize the Ralph loop:

🔄 Ralph loop activated in this session!

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

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

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

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

🔄

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

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

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

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

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

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

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

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

I'll start by reading the ROADMAP.md to understand the current state and identify the first task to work on.

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.

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.

Now let me check the GameState struct for combat_state and the damage-dealing functions.

Let me check how DealDamage is executed in game.rs, and also how the AI implementations handle select_attackers/select_blockers.

Now let me check the AI implementations for select_attackers/select_blockers.

Let me check the heuristic and random player implementations more efficiently.

Let me also check how AlwaysPassPlayer handles these methods, and the Permanent methods for tapping/attacking.

Now let me find the AlwaysPassPlayer in game.rs and understand how the test player works.

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.

Request interrupted by user

Summary: Keyword Abilities & State-Based Actions in mtg-rl Engine

Keyword Abilities Status

Mechanically Enforced Keywords

Keywords with Partial/Limited Support

Keywords as Decorative Flags (Not Enforced)

State-Based Actions (Checked in state.rs:check_state_based_actions())

Critical Limitation: Combat Phase Not Implemented

Summary Table

Files Involved

Comprehensive MTG-RL Engine Inventory

OVERVIEW

1. EFFECT SYSTEM (abilities.rs)

FULLY IMPLEMENTED (with real match arms in execute_effects):

NO IMPLEMENTATION (catch-all _ => {}):

NOTES ON IMPLEMENTATIONS:

2. STATIC EFFECTS (abilities.rs)

FULLY DEFINED (for card data):

ENFORCEMENT STATUS:

3. COST SYSTEM (abilities.rs)

FULLY IMPLEMENTED in pay_costs():

PARTIALLY IMPLEMENTED:

4. EVENT SYSTEM (events.rs)

CATEGORIZED BY TYPE:

USAGE IN TRIGGERED ABILITIES:

5. GAME LOOP (game.rs)

TURN STRUCTURE (PhaseStep enum from constants.rs):

GAME LOOP FLOW (process_step):

FEATURES:

LIMITATIONS:

6. ZONE MANAGEMENT (zones.rs, constants.rs)

ZONE INFRASTRUCTURE:

7. MANA SYSTEM (mana.rs, mana_pool.rs)

FEATURES:

LIMITATIONS:

8. COMBAT SYSTEM (combat.rs, game.rs)

CombatState Struct:

CombatGroup:

VALIDATED:

SIMPLIFIED:

9. TARGETING SYSTEM (abilities.rs, targets.rs, decision.rs)

FEATURES:

10. KEYWORD ABILITIES (constants.rs)

ENFORCEMENT:

CHECKING:

11. CONTINUOUS EFFECTS & LAYERS (effects.rs)

IMPLEMENTATION STATUS:

LIMITATIONS:

12. REPLACEMENT EFFECTS (effects.rs)

IMPLEMENTATION STATUS:

13. PLAYER DECISION MAKING (decision.rs)

14. COUNTER SYSTEM (counters.rs, permanent.rs)

Core:

Named:

USAGE:

15. CARD & PERMANENT SYSTEM (card.rs, permanent.rs)

16. ABILITY STORE & RESOLUTION (abilities.rs, game.rs)

MISSING/TODO FEATURES

From game.rs TODO comments:

From code review:

ARCHITECTURE STRENGTHS

PERFORMANCE NOTES

KEY FILES BY FUNCTION

RUST CARD IMPLEMENTATIONS CUSTOM USAGE ANALYSIS

Executive Summary

EFFECT::CUSTOM ANALYSIS (747 total)

Top Categories by Volume

Top 20 Most Common Effect::Custom Patterns

Notable Effect::Custom Patterns Requiring Engine Implementation

STATICEFFECT::CUSTOM ANALYSIS (160 total)

By Category

Notable StaticEffect::Custom Patterns

COST::CUSTOM ANALYSIS (33 total)

Notable Cost::Custom Patterns

CATEGORIZED ENGINE FEATURE GAPS

CRITICAL (Would eliminate 100+ customs each)

HIGH (Would eliminate 20-100 customs each)

MEDIUM (Would eliminate 10-20 customs each)

LOWER (Single-digit impact each but notable)

SET-SPECIFIC INSIGHTS

RECOMMENDATIONS FOR PRIORITIZATION

State-Based Actions (Checked in `state.rs:check_state_based_actions()`)

NO IMPLEMENTATION (catch-all `_ => {}`):