Rummage - MTG Commander Game Engine Documentation

Welcome to the official documentation for Rummage, a robust end-to-end tested Magic: The Gathering Commander format game engine built with Bevy 0.15.x.

About Rummage

Rummage is a modern, open-source implementation of the Magic: The Gathering Commander format, focusing on correctness, performance, and extensibility. Built on Bevy's Entity Component System (ECS) architecture, Rummage provides a solid foundation for complex card interactions while maintaining deterministic gameplay essential for networked multiplayer.

Our goal is to create a comprehensive digital implementation that faithfully reproduces the Commander experience while leveraging modern game engine technologies.

Documentation Structure

The documentation is organized into interconnected sections that guide you from understanding MTG rules to technical implementation details:

1. MTG Rules Reference - High-level explanations of Magic: The Gathering rules, serving as a bridge between official rules and our implementation
2. MTG Core Rules - Implementation of fundamental Magic: The Gathering rules that form the foundation of all gameplay
3. Game Formats - Format-specific rules implementation, currently focusing on the Commander format
4. Game UI - User interface systems for visualizing and interacting with the game state
5. Networking - Multiplayer functionality using bevy_replicon for synchronized gameplay
6. Card Systems - Card representation, effects, and interactions that drive gameplay
7. Testing - Comprehensive testing framework to ensure rule correctness and system reliability
8. Development - Guidelines and tools for contributors to the Rummage project
9. API Reference - Technical documentation of Rummage's code structure and interfaces

These sections follow a logical progression:

• The MTG Rules Reference explains what the rules are
• The MTG Core Rules and Game Formats explain how we implement these rules
• The remaining sections cover the technical systems that support this implementation

Getting Started

If you're new to the project, we recommend exploring the documentation in this order:

1. MTG Core Rules Overview - Understand how Rummage implements the fundamental MTG rules
2. Commander Format Overview - Learn about the Commander-specific rules and mechanics
3. Development Guide - Set up your development environment
4. Bevy ECS Guide - Learn how we use Bevy's Entity Component System
5. Testing Overview - Understand our testing approach and methodology

Technical Architecture

Rummage integrates several key technologies:

1. Bevy 0.15.x - Entity Component System (ECS) game engine that provides the architectural foundation
2. Bevy Replicon - Networking and state synchronization for multiplayer gameplay
3. Rust - Memory-safe, high-performance language for reliable game logic

Our architecture follows these principles:

1. Entity Component System - Game elements are composed of entities with components, providing a flexible and performant structure for representing cards, players, and game state
2. Event-driven Architecture - Systems communicate through events, enabling loose coupling and flexible interactions
3. Data-oriented Design - Optimized for cache coherence and performance, critical for handling complex board states
4. Deterministic Game Logic - Ensures consistency across network play by maintaining predictable state transitions
5. Snapshot System - Enables game state serialization for networking, replays, and save/load functionality

Implementation Status

This documentation represents both implemented features and design specifications for planned features. Components are marked as follows:

• ✅ Implemented and tested
• 🔄 In progress
• ⚠️ Planned but not yet implemented

Development Standards

The Rummage codebase adheres to the following standards:

1. Bevy 0.15.x Compatibility: Using non-deprecated Bevy APIs (e.g., Text2d instead of Text2dBundle)
2. End-to-End Testing: Comprehensive test coverage for all features
3. Documentation-First Development: New features are documented before implementation
4. Performance Focus: Optimization for smooth gameplay even with complex board states

Contributing

If you're interested in contributing to the Rummage project, please review:

1. Contribution Guidelines
2. Documentation Guide
3. Code Style Guide

Reference Materials

The implementation is based on official MTG rules:

• Magic: The Gathering Comprehensive Rules
• Commander Format Rules

A local copy of the comprehensive rules is available in this repository: MagicCompRules 20250207.txt.

This documentation will evolve as the project progresses. Last updated: March 2025.

MTG Core Rules

This section documents the implementation of fundamental Magic: The Gathering rules in the Rummage engine.

Overview

The MTG Core Rules module implements the foundational mechanics defined in the Magic: The Gathering Comprehensive Rules, forming the basis for all supported game formats. These include:

• Turn structure and phase sequence
• Card types, characteristics, and properties
• Game zones and zone transitions
• Stack implementation and resolution mechanics
• State-based actions
• Combat system
• Mana and casting costs

Implementation Architecture

Rummage implements MTG rules using Bevy's Entity Component System (ECS) architecture:

This architecture creates a clean separation between game data and logic, enabling:

• Higher testability of individual game mechanics
• Parallel processing of independent game systems
• Easier extension for format-specific rules
• Greater code modularity and maintainability

For implementation details, see ECS Implementation.

Core Game Elements

Turn Structure

MTG turns follow a fixed sequence of phases and steps:

1. Beginning Phase

   • Untap: Active player untaps their permanents
   • Upkeep: Triggers "at beginning of upkeep" abilities
   • Draw: Active player draws a card

2. Pre-Combat Main Phase

   • Player may play lands and cast spells

3. Combat Phase

   • Beginning of Combat: Last chance for effects before attacks
   • Declare Attackers: Active player declares attacking creatures
   • Declare Blockers: Defending players assign blockers
   • Combat Damage: Creatures deal damage
   • End of Combat: Triggers "at end of combat" abilities

4. Post-Combat Main Phase

   • Player may play lands (if not done in first main phase) and cast spells

5. Ending Phase

   • End Step: Triggers "at beginning of end step" abilities
   • Cleanup: Damage clears, "until end of turn" effects end

Each phase transition is implemented as a state change, with systems that execute appropriate actions for each phase.

Game Zones

MTG defines distinct zones where cards can exist:

Each zone is implemented as an entity with components that track contained cards. Zone transitions trigger specific events and state updates.

Card Types and Characteristics

The engine supports all standard MTG card types:

• Land: Produces mana
• Creature: Can attack and block
• Artifact: Represents magical items
• Enchantment: Ongoing magical effects
• Planeswalker: Powerful ally with loyalty abilities
• Instant: One-time effect at any time
• Sorcery: One-time effect during main phase

Cards are represented as entities with components describing their characteristics (name, types, mana cost, etc.) and current state.

Stack and Priority

The stack is MTG's core mechanic for resolving spells and abilities:

1. Active player receives priority first in each step/phase
2. Players may cast spells/activate abilities when they have priority
3. Spells/abilities go on the stack when cast/activated
4. When all players pass priority consecutively, the top item on the stack resolves
5. After resolution, active player receives priority again

Our implementation uses a dedicated stack system integrated with a priority manager that tracks which player can act.

State-Based Actions

State-based actions are automatic game rules that check and apply whenever a player would receive priority:

• Creatures with toughness ≤ 0 are put into their owners' graveyards
• Players with life ≤ 0 lose the game
• Auras without legal targets are put into owners' graveyards
• Legendary permanents with the same name are put into graveyards
• And many more...

These are implemented as systems that run at specific points in the game loop to enforce rules consistency.

Format Extensibility

The core rules are implemented in a format-agnostic way to enable:

1. Consistent Base Behavior: All formats share the same fundamental mechanics
2. Extension Points: Format-specific plugins can override or extend core behavior
3. Configuration: Format-specific parameters (starting life, deck requirements, etc.)

For Commander-specific implementations that build upon these core rules, see the Commander Format section.

Technical Components

The core rules implementation includes these key technical components:

• Turn Manager: Controls phase/step progression
• Zone Manager: Handles card movement between zones
• Stack Resolution Engine: Manages spell/ability resolution
• State-Based Action Checker: Enforces automatic game rules
• Combat Resolver: Handles attack/block/damage processes
• Mana System: Tracks and processes mana production/consumption

Each component is implemented as a Bevy plugin that adds relevant systems, components, and resources.

Next Steps

• Turn Structure: Detailed implementation of turn phases and steps
• Zones: Implementation of game zones and zone transitions
• Stack: Stack implementation and priority system
• State-Based Actions: Implementation of automatic game rules
• Combat: Combat phase implementation
• ECS Implementation: Technical details of the ECS approach

Turn Structure

This section documents the core implementation of Magic: The Gathering's turn structure and phase system in Rummage.

Overview

The turn structure in Magic: The Gathering follows a specific sequence of phases and steps, during which players can take actions at defined points. This structured progression is essential for maintaining game order and ensuring rules consistency.

Turn Phases and Steps

A turn in MTG consists of the following phases and steps, in order:

1. Beginning Phase

   • Untap Step - Active player untaps their permanents
   • Upkeep Step - Triggers "at the beginning of your upkeep" abilities
   • Draw Step - Active player draws a card

2. First Main Phase (Precombat Main Phase)

   • Player may play lands, cast spells, and activate abilities

3. Combat Phase

   • Beginning of Combat Step - Last chance for effects before attackers
   • Declare Attackers Step - Active player declares attackers
   • Declare Blockers Step - Defending players declare blockers
   • Combat Damage Step - Combat damage is assigned and dealt
   • End of Combat Step - Last chance for effects before combat ends

4. Second Main Phase (Postcombat Main Phase)

   • Player may play lands (if they haven't during this turn), cast spells, and activate abilities

5. Ending Phase

   • End Step - Triggers "at the beginning of your end step" abilities
   • Cleanup Step - Discard to hand size, damage wears off

Implementation Details

Phase Tracking

#![allow(unused)]
fn main() {
#[derive(Resource, Debug, Clone, PartialEq, Eq)]
pub enum Phase {
    Beginning(BeginningPhaseStep),
    Main(MainPhaseType),
    Combat(CombatStep),
    Ending(EndingPhaseStep),
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum BeginningPhaseStep {
    Untap,
    Upkeep,
    Draw,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum MainPhaseType {
    Precombat,
    Postcombat,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CombatStep {
    Beginning,
    DeclareAttackers,
    DeclareBlockers,
    CombatDamage,
    End,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum EndingPhaseStep {
    End,
    Cleanup,
}
}

Phase Progression System

The phase progression system handles the advancement through turn phases:

#![allow(unused)]
fn main() {
pub fn advance_phase(
    mut game_state: ResMut<GameState>,
    mut phase_events: EventWriter<PhaseChangeEvent>,
) {
    let current_phase = game_state.current_phase.clone();
    let next_phase = determine_next_phase(&current_phase);
    
    game_state.current_phase = next_phase.clone();
    
    phase_events.send(PhaseChangeEvent {
        previous_phase: current_phase,
        new_phase: next_phase,
    });
}

fn determine_next_phase(current_phase: &Phase) -> Phase {
    match current_phase {
        Phase::Beginning(step) => match step {
            BeginningPhaseStep::Untap => Phase::Beginning(BeginningPhaseStep::Upkeep),
            BeginningPhaseStep::Upkeep => Phase::Beginning(BeginningPhaseStep::Draw),
            BeginningPhaseStep::Draw => Phase::Main(MainPhaseType::Precombat),
        },
        Phase::Main(MainPhaseType::Precombat) => Phase::Combat(CombatStep::Beginning),
        Phase::Combat(step) => match step {
            CombatStep::Beginning => Phase::Combat(CombatStep::DeclareAttackers),
            CombatStep::DeclareAttackers => Phase::Combat(CombatStep::DeclareBlockers),
            CombatStep::DeclareBlockers => Phase::Combat(CombatStep::CombatDamage),
            CombatStep::CombatDamage => Phase::Combat(CombatStep::End),
            CombatStep::End => Phase::Main(MainPhaseType::Postcombat),
        },
        Phase::Main(MainPhaseType::Postcombat) => Phase::Ending(EndingPhaseStep::End),
        Phase::Ending(step) => match step {
            EndingPhaseStep::End => Phase::Ending(EndingPhaseStep::Cleanup),
            EndingPhaseStep::Cleanup => Phase::Beginning(BeginningPhaseStep::Untap),
        },
    }
}
}

Priority System

During most phases and steps, players receive priority to take actions:

#![allow(unused)]
fn main() {
pub fn handle_priority(
    game_state: Res<GameState>,
    mut stack: ResMut<Stack>,
    mut priority_events: EventWriter<PriorityEvent>,
) {
    // Skip priority in certain steps
    if !should_players_get_priority(&game_state.current_phase) {
        return;
    }
    
    // Determine priority holder
    let active_player = game_state.active_player;
    let next_player = determine_priority_player(active_player, &game_state.player_order);
    
    priority_events.send(PriorityEvent {
        player: next_player,
        phase: game_state.current_phase.clone(),
    });
}

fn should_players_get_priority(phase: &Phase) -> bool {
    match phase {
        Phase::Beginning(BeginningPhaseStep::Untap) => false,
        Phase::Ending(EndingPhaseStep::Cleanup) => false,
        _ => true,
    }
}
}

Extension Points

The turn structure system is designed to be extensible for different formats:

1. Format-Specific Phases - Formats can add custom phases or steps
2. Turn Modification - Systems for extra turns, skipped turns, or additional phases
3. Priority Rules - Customizable priority passing for different formats

Integration with Other Systems

The turn structure integrates with these other game systems:

• State-Based Actions - Checked whenever a player would receive priority
• Stack Resolution - Occurs during priority passes when no player adds to the stack
• Triggered Abilities - Put on the stack at appropriate times based on the current phase
• Mana System - Mana pools empty at phase boundaries

Format-Specific Considerations

Different Magic formats may implement turn structure variations:

• Multiplayer Formats - Handle turn order for multiple players
• Special Formats - May modify turn structure (e.g., Two-Headed Giant)

For Commander-specific turn structure implementation, see Commander Turn Structure.

Next: Priority System

Priority System

This document details the implementation of the priority system in Rummage, which determines which player can take actions at any given time during a game of Magic: The Gathering.

Overview

The priority system is a fundamental part of Magic: The Gathering's turn structure. It determines when players can cast spells, activate abilities, and take other game actions. Understanding and correctly implementing the priority system is essential for proper game flow.

Core Priority Rules

The basic rules of priority in MTG are:

1. The active player receives priority first in each step and phase
2. When a player has priority, they may:
   • Cast a spell
   • Activate an ability
   • Take a special action
   • Pass priority
3. When a player passes priority, the next player in turn order receives priority
4. When all players pass priority in succession:
   • If the stack is empty, the current step or phase ends
   • If the stack has objects, the top object on the stack resolves, then the active player gets priority again

Implementation

In Rummage, the priority system is implemented as follows:

#![allow(unused)]
fn main() {
#[derive(Resource)]
pub struct PrioritySystem {
    // The player who currently has priority
    pub current_player: Entity,
    
    // Set of players who have passed priority in succession
    pub passed_players: HashSet<Entity>,
    
    // Whether the priority system is currently active
    pub active: bool,
}

#[derive(Event)]
pub struct PriorityEvent {
    pub player: Entity,
    pub action: PriorityAction,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PriorityAction {
    Receive,  // Player receives priority
    Pass,     // Player passes priority
    TakeAction, // Player takes an action (cast spell, activate ability, etc.)
}
}

Priority Flow

The flow of priority follows this pattern:

1. Phase/Step Start: At the beginning of each phase or step, the active player receives priority
2. Action Taken: If a player takes an action, all players who have passed are reset, and priority returns to the active player
3. Passing: When a player passes, the next player in turn order receives priority
4. Resolution: When all players pass in succession, either the top of the stack resolves or the phase/step ends

Priority System Implementation

#![allow(unused)]
fn main() {
pub fn handle_priority_system(
    mut commands: Commands,
    mut priority: ResMut<PrioritySystem>,
    mut priority_events: EventReader<PriorityEvent>,
    game_state: Res<GameState>,
    stack: Res<Stack>,
) {
    for event in priority_events.iter() {
        match event.action {
            PriorityAction::Pass => {
                // Record that this player passed
                priority.passed_players.insert(event.player);
                
                // Check if all players have passed
                if priority.passed_players.len() == game_state.players.len() {
                    // All players have passed
                    if !stack.items.is_empty() {
                        // Resolve top of stack
                        commands.add(resolve_stack_command());
                        
                        // Reset passed players
                        priority.passed_players.clear();
                        
                        // Active player gets priority again
                        priority.current_player = game_state.active_player;
                    } else {
                        // Stack is empty, end current phase/step
                        commands.add(advance_phase_command());
                        
                        // Priority will be set by the phase transition system
                        priority.active = false;
                    }
                } else {
                    // Not all players have passed, give priority to next player
                    let next_player = get_next_player(event.player, &game_state);
                    priority.current_player = next_player;
                }
            },
            PriorityAction::TakeAction => {
                // Player took an action, reset passed players
                priority.passed_players.clear();
                
                // Active player gets priority again
                priority.current_player = game_state.active_player;
            },
            PriorityAction::Receive => {
                // Player receives priority (usually at beginning of phase/step)
                priority.current_player = event.player;
                priority.active = true;
            }
        }
    }
}
}

Special Priority Rules

No Priority Phases

Some steps do not normally grant players priority:

• Untap Step: No player receives priority during this step
• Cleanup Step: No player receives priority unless a triggered ability triggers

#![allow(unused)]
fn main() {
pub fn should_grant_priority(phase: Phase, step: Step) -> bool {
    match (phase, step) {
        (Phase::Beginning, Step::Untap) => false,
        (Phase::Ending, Step::Cleanup) => false,
        _ => true,
    }
}
}

Triggered Abilities During No-Priority Steps

If a triggered ability triggers during a step where players don't normally receive priority, players will receive priority:

#![allow(unused)]
fn main() {
pub fn handle_cleanup_triggers(
    mut commands: Commands,
    mut priority: ResMut<PrioritySystem>,
    game_state: Res<GameState>,
    triggers: Res<TriggeredAbilities>,
) {
    // If we're in cleanup step and there are triggers
    if game_state.current_phase == Phase::Ending && 
       game_state.current_step == Step::Cleanup &&
       !triggers.pending.is_empty() {
        
        // Grant priority to active player
        priority.active = true;
        priority.current_player = game_state.active_player;
        priority.passed_players.clear();
    }
}
}

APNAP Order

When multiple players would receive priority simultaneously (such as for triggered abilities), they are processed in APNAP (Active Player, Non-Active Player) order:

#![allow(unused)]
fn main() {
pub fn get_players_in_apnap_order(game_state: &GameState) -> Vec<Entity> {
    let mut players = Vec::new();
    
    // Start with active player
    let mut current = game_state.active_player;
    players.push(current);
    
    // Add remaining players in turn order
    for _ in 1..game_state.players.len() {
        current = get_next_player(current, game_state);
        players.push(current);
    }
    
    players
}
}

Integration with Other Systems

The priority system integrates with:

1. Turn Structure: Phase and step transitions affect priority
2. Stack System: Stack resolution and priority are tightly coupled
3. Action System: Player actions affect priority flow
4. UI System: The UI must indicate which player has priority

Implementation Status

The priority system implementation currently:

• ✅ Handles basic priority passing
• ✅ Integrates with stack resolution
• ✅ Implements APNAP order
• ✅ Handles special steps without priority
• ✅ Supports triggered abilities during cleanup
• 🔄 Implementing special actions that don't use the stack
• 🔄 Handling priority with split second spells

Next: Turn Phases

Turn Phases

This document details the implementation of turn phases and steps in Rummage, explaining how the game progresses through the structured sequence of a Magic: The Gathering turn.

Phase and Step Structure

A turn in Magic: The Gathering consists of five phases, some of which are divided into steps:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Phase {
    Beginning,
    PreCombatMain,
    Combat,
    PostCombatMain,
    Ending,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Step {
    // Beginning Phase
    Untap,
    Upkeep,
    Draw,
    
    // Main Phase (no steps)
    Main,
    
    // Combat Phase
    BeginningOfCombat,
    DeclareAttackers,
    DeclareBlockers,
    CombatDamage,
    FirstStrikeDamage, // Only used when first/double strike is involved
    EndOfCombat,
    
    // Ending Phase
    End,
    Cleanup,
}
}

Phase Transitions

The game progresses through phases and steps in a specific order. This is managed by a phase transition system:

#![allow(unused)]
fn main() {
pub fn phase_transition_system(
    mut commands: Commands,
    mut game_state: ResMut<GameState>,
    mut phase_events: EventWriter<PhaseChangeEvent>,
    mut step_events: EventWriter<StepChangeEvent>,
    stack: Res<Stack>,
    priority: Res<PrioritySystem>,
) {
    // Only transition if priority is not active and stack is empty
    if priority.active || !stack.items.is_empty() {
        return;
    }
    
    // Current phase and step
    let current_phase = game_state.current_phase;
    let current_step = game_state.current_step;
    
    // Determine next phase and step
    let (next_phase, next_step) = get_next_phase_step(current_phase, current_step);
    
    // Update game state
    game_state.current_phase = next_phase;
    game_state.current_step = next_step;
    
    // Send events
    if current_phase != next_phase {
        phase_events.send(PhaseChangeEvent {
            previous: current_phase,
            current: next_phase,
        });
    }
    
    step_events.send(StepChangeEvent {
        previous: current_step,
        current: next_step,
    });
    
    // Execute phase/step entry actions
    execute_phase_entry_actions(next_phase, next_step, &mut commands, &game_state);
}
}

Phase Progression

The progression from one phase/step to the next follows this pattern:

#![allow(unused)]
fn main() {
fn get_next_phase_step(current_phase: Phase, current_step: Step) -> (Phase, Step) {
    match (current_phase, current_step) {
        // Beginning Phase progression
        (Phase::Beginning, Step::Untap) => (Phase::Beginning, Step::Upkeep),
        (Phase::Beginning, Step::Upkeep) => (Phase::Beginning, Step::Draw),
        (Phase::Beginning, Step::Draw) => (Phase::PreCombatMain, Step::Main),
        
        // Pre-Combat Main Phase progression
        (Phase::PreCombatMain, Step::Main) => (Phase::Combat, Step::BeginningOfCombat),
        
        // Combat Phase progression
        (Phase::Combat, Step::BeginningOfCombat) => (Phase::Combat, Step::DeclareAttackers),
        (Phase::Combat, Step::DeclareAttackers) => (Phase::Combat, Step::DeclareBlockers),
        (Phase::Combat, Step::DeclareBlockers) => {
            // Check if first strike is needed
            if combat_has_first_strike() {
                (Phase::Combat, Step::FirstStrikeDamage)
            } else {
                (Phase::Combat, Step::CombatDamage)
            }
        },
        (Phase::Combat, Step::FirstStrikeDamage) => (Phase::Combat, Step::CombatDamage),
        (Phase::Combat, Step::CombatDamage) => (Phase::Combat, Step::EndOfCombat),
        (Phase::Combat, Step::EndOfCombat) => (Phase::PostCombatMain, Step::Main),
        
        // Post-Combat Main Phase progression
        (Phase::PostCombatMain, Step::Main) => (Phase::Ending, Step::End),
        
        // Ending Phase progression
        (Phase::Ending, Step::End) => (Phase::Ending, Step::Cleanup),
        (Phase::Ending, Step::Cleanup) => {
            // Move to next turn
            (Phase::Beginning, Step::Untap)
        },
        
        // Default case (should never happen)
        _ => (current_phase, current_step),
    }
}
}

Phase Entry Actions

Each phase and step has specific actions that occur when entering:

#![allow(unused)]
fn main() {
fn execute_phase_entry_actions(
    phase: Phase,
    step: Step,
    commands: &mut Commands,
    game_state: &GameState,
) {
    match (phase, step) {
        // Beginning Phase actions
        (Phase::Beginning, Step::Untap) => {
            // Untap all permanents controlled by active player
            commands.add(untap_permanents_command(game_state.active_player));
            
            // Handle "at beginning of untap step" triggers
            commands.add(check_beginning_of_step_triggers_command(phase, step));
        },
        (Phase::Beginning, Step::Upkeep) => {
            // Handle "at beginning of upkeep" triggers
            commands.add(check_beginning_of_step_triggers_command(phase, step));
            
            // Grant priority to active player
            commands.add(grant_priority_command(game_state.active_player));
        },
        (Phase::Beginning, Step::Draw) => {
            // Active player draws a card (except on first turn)
            if game_state.turn_number > 1 {
                commands.add(draw_card_command(game_state.active_player, 1));
            }
            
            // Handle "at beginning of draw step" triggers
            commands.add(check_beginning_of_step_triggers_command(phase, step));
            
            // Grant priority to active player
            commands.add(grant_priority_command(game_state.active_player));
        },
        
        // Main Phase actions
        (Phase::PreCombatMain, Step::Main) | (Phase::PostCombatMain, Step::Main) => {
            // Reset land plays for turn if entering first main phase
            if phase == Phase::PreCombatMain && game_state.current_phase != Phase::PreCombatMain {
                commands.add(reset_land_plays_command());
            }
            
            // Grant priority to active player
            commands.add(grant_priority_command(game_state.active_player));
        },
        
        // Combat Phase actions
        (Phase::Combat, _) => {
            // Handle specific combat step actions
            match step {
                Step::BeginningOfCombat => {
                    // Handle "at beginning of combat" triggers
                    commands.add(check_beginning_of_step_triggers_command(phase, step));
                },
                Step::DeclareAttackers => {
                    // Active player declares attackers
                    commands.add(declare_attackers_command());
                },
                Step::DeclareBlockers => {
                    // Defending players declare blockers
                    commands.add(declare_blockers_command());
                },
                Step::FirstStrikeDamage => {
                    // Assign and deal first strike damage
                    commands.add(assign_first_strike_damage_command());
                    commands.add(deal_combat_damage_command(true));
                },
                Step::CombatDamage => {
                    // Assign and deal regular combat damage
                    commands.add(assign_combat_damage_command());
                    commands.add(deal_combat_damage_command(false));
                },
                _ => {}
            }
            
            // Grant priority to active player (for all combat steps)
            commands.add(grant_priority_command(game_state.active_player));
        },
        
        // Ending Phase actions
        (Phase::Ending, Step::End) => {
            // Handle "at beginning of end step" triggers
            commands.add(check_beginning_of_step_triggers_command(phase, step));
            
            // Grant priority to active player
            commands.add(grant_priority_command(game_state.active_player));
        },
        (Phase::Ending, Step::Cleanup) => {
            // Discard to hand size
            commands.add(discard_to_hand_size_command(game_state.active_player));
            
            // Remove "until end of turn" effects
            commands.add(remove_until_end_of_turn_effects_command());
            
            // Clear damage from permanents
            commands.add(clear_damage_command());
            
            // No priority is granted in cleanup step unless a trigger occurs
        },
    }
}
}

Turn Advancement

When a turn ends, the game advances to the next player's turn:

#![allow(unused)]
fn main() {
fn advance_turn_system(
    mut commands: Commands,
    mut game_state: ResMut<GameState>,
    mut turn_events: EventWriter<TurnChangeEvent>,
) {
    // Only advance turn when transitioning from cleanup to untap
    if game_state.current_phase == Phase::Ending && 
       game_state.current_step == Step::Cleanup &&
       !game_state.transitioning_to_next_turn {
        
        // Mark that we're transitioning to next turn
        game_state.transitioning_to_next_turn = true;
        
        // Get next player
        let next_player = get_next_player(game_state.active_player, &game_state);
        
        // Send turn change event
        turn_events.send(TurnChangeEvent {
            previous_player: game_state.active_player,
            next_player,
            turn_number: game_state.turn_number + 1,
        });
        
        // Update game state
        game_state.active_player = next_player;
        game_state.turn_number += 1;
        
        // Reset turn-based tracking
        commands.add(reset_turn_tracking_command());
    }
}
}

Extra Turns

The system also supports extra turns, which are handled by modifying the turn order:

#![allow(unused)]
fn main() {
pub fn add_extra_turn(
    player: Entity,
    game_state: &mut GameState,
    extra_turn_events: &mut EventWriter<ExtraTurnEvent>,
) {
    // Add extra turn to the queue
    game_state.extra_turns.push(player);
    
    // Send event
    extra_turn_events.send(ExtraTurnEvent {
        player,
        source_turn: game_state.turn_number,
    });
}

fn determine_next_turn_player(game_state: &GameState) -> Entity {
    // Check if there are extra turns queued
    if !game_state.extra_turns.is_empty() {
        // Take the next extra turn
        return game_state.extra_turns[0];
    }
    
    // Otherwise, proceed to next player in turn order
    get_next_player(game_state.active_player, game_state)
}
}

Implementation Status

The turn structure implementation currently:

• ✅ Handles all standard phases and steps
• ✅ Implements proper phase transitions
• ✅ Supports phase-specific actions
• ✅ Manages turn advancement
• ✅ Supports extra turns
• 🔄 Implementing special turn modifications (e.g., additional combat phases)
• 🔄 Supporting time counters and suspended cards

Next: Combat System

Game Zones

Overview

Zones are distinct areas where cards can exist during a game of Magic: The Gathering. This section documents the core implementation of game zones in Rummage, which serve as the foundation for all MTG formats.

Standard Game Zones

Magic: The Gathering has the following standard game zones:

1. Library - The player's deck of cards, face down and in a randomized order
2. Hand - Cards held by a player, visible only to that player (unless affected by card effects)
3. Battlefield - Where permanents (lands, creatures, artifacts, enchantments, planeswalkers) exist in play
4. Graveyard - Discard pile for destroyed, sacrificed, or discarded cards, face up
5. Stack - Where spells and abilities wait to resolve
6. Exile - Cards removed from the game, face up unless specified otherwise

Additionally, some formats introduce special zones:

• Command Zone - Used primarily in Commander format for commanders and emblems

Core Zone Implementation

Each zone is implemented as an entity with components that track its contained cards. The zone system manages the movement of cards between zones according to the MTG rules.

Zone Management Components

#![allow(unused)]
fn main() {
#[derive(Resource)]
pub struct ZoneManager {
    // Maps player entities to their personal zones (library, hand, graveyard)
    pub player_zones: HashMap<Entity, PlayerZones>,
    
    // Shared zones (battlefield, stack, exile)
    pub battlefield: Entity,
    pub stack: Entity,
    pub exile: Entity,
    
    // Format-specific zones can be added by plugins
    pub command_zone: Option<Entity>,
}

#[derive(Component)]
pub struct Zone {
    pub zone_type: ZoneType,
    pub owner: Option<Entity>, // None for shared zones
    pub cards: Vec<Entity>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ZoneType {
    Library,
    Hand,
    Battlefield,
    Graveyard,
    Stack,
    Exile,
    Command,
}

pub struct PlayerZones {
    pub library: Entity,
    pub hand: Entity,
    pub graveyard: Entity,
}
}

Zone Transitions

When a card moves from one zone to another, a zone transition occurs. These transitions are managed by the zone system and can trigger abilities based on the zones involved.

Zone Transition Events

#![allow(unused)]
fn main() {
#[derive(Event)]
pub struct ZoneTransitionEvent {
    pub card: Entity,
    pub from_zone: Entity,
    pub to_zone: Entity,
    pub reason: ZoneTransitionReason,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ZoneTransitionReason {
    Cast,
    Resolve,
    Destroy,
    Sacrifice,
    Discard,
    Draw,
    ReturnToHand,
    PutIntoPlay,
    Exile,
    ShuffleIntoLibrary,
    // ...and more
}
}

Zone Transition System

#![allow(unused)]
fn main() {
pub fn handle_zone_transitions(
    mut commands: Commands,
    mut zone_events: EventReader<ZoneTransitionEvent>,
    mut zones: Query<&mut Zone>,
    mut triggered_abilities: EventWriter<TriggeredAbilityEvent>,
    cards: Query<&Card>,
) {
    for event in zone_events.iter() {
        // Remove card from source zone
        if let Ok(mut source_zone) = zones.get_mut(event.from_zone) {
            if let Some(index) = source_zone.cards.iter().position(|&c| c == event.card) {
                source_zone.cards.remove(index);
            }
        }
        
        // Add card to destination zone
        if let Ok(mut dest_zone) = zones.get_mut(event.to_zone) {
            dest_zone.cards.push(event.card);
        }
        
        // Check for triggered abilities based on zone transitions
        if let Ok(card) = cards.get(event.card) {
            // Process any "when this card enters/leaves a zone" abilities
            // ...
        }
    }
}
}

Zone-Specific Rules

Each zone has specific rules that govern how cards interact within and with that zone:

Library

• Cards are face down and in random order
• Players draw from the top
• Running out of cards to draw results in a loss

Hand

• Cards are visible only to their owner
• Hand size is normally limited to 7 at end of turn
• Players discard down to maximum hand size during cleanup

Battlefield

• Only permanents can exist on the battlefield
• Cards on the battlefield are affected by "summoning sickness"
• Most abilities can only be activated from the battlefield

Graveyard

• Cards are face up and can be seen by all players
• Order of cards matters for some effects
• Some abilities function from the graveyard

Stack

• Spells and abilities go on the stack before resolving
• The stack resolves in "last in, first out" order
• All players get priority between stack resolutions

Exile

• Cards are face up by default
• Exiled cards are generally inaccessible
• Some effects allow interaction with exiled cards

Format Extensions

Different formats may extend or modify the basic zone system:

• Commander Format: Adds the Command Zone for commanders
• Planechase: Adds a plane card zone
• Archenemy: Adds a scheme card zone

For format-specific zone mechanics like the Command Zone in Commander, see the respective format documentation.

Next: Zone Transitions

Stack and Priority System

Overview

The stack is a fundamental mechanic in Magic: The Gathering, representing the order in which spells and abilities resolve. This section documents the core implementation of the stack and priority system in Rummage.

The Stack

The stack is a last-in, first-out (LIFO) data structure that determines the order in which spells and abilities resolve during gameplay.

Stack Implementation

#![allow(unused)]
fn main() {
#[derive(Resource)]
pub struct Stack {
    // The stack itself - a list of stack items in order
    pub items: Vec<StackItem>,
    
    // The currently resolving stack item, if any
    pub currently_resolving: Option<StackItem>,
    
    // Temporary storage for abilities that trigger during resolution
    pub pending_triggers: Vec<TriggeredAbility>,
}

#[derive(Clone, Debug)]
pub struct StackItem {
    pub id: Entity,
    pub item_type: StackItemType,
    pub controller: Entity,
    pub source: Entity,
    pub targets: Vec<StackTarget>,
    pub effects: Vec<Effect>,
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub enum StackItemType {
    Spell(CardType),
    Ability(AbilityType),
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub enum AbilityType {
    Activated,
    Triggered,
    Static, // Static abilities generally don't use the stack but are tracked here for targeting purposes
    Mana,   // Mana abilities don't use the stack but may be tracked here
}
}

Stack Order and Resolution

The stack follows these core principles:

1. The active player gets priority first in each phase and step
2. When a player has priority, they can cast spells or activate abilities
3. Each spell or ability goes on top of the stack
4. After a spell or ability is put on the stack, all players get priority again
5. When all players pass priority in succession, the top item of the stack resolves
6. After resolution, the active player gets priority again

Stack Resolution System

#![allow(unused)]
fn main() {
pub fn resolve_stack(
    mut commands: Commands,
    mut stack: ResMut<Stack>,
    mut game_state: ResMut<GameState>,
    mut zone_transitions: EventWriter<ZoneTransitionEvent>,
    mut effect_events: EventWriter<EffectEvent>,
) {
    // Check if there's something to resolve
    if stack.items.is_empty() {
        return;
    }
    
    // Get the top item
    let item = stack.items.pop().unwrap();
    stack.currently_resolving = Some(item.clone());
    
    // Process based on item type
    match item.item_type {
        StackItemType::Spell(card_type) => {
            // Process spell resolution
            // Move card to appropriate zone (battlefield for permanents, graveyard for others)
            // ...
        },
        StackItemType::Ability(ability_type) => {
            // Process ability resolution
            // ...
        }
    }
    
    // Process effects
    for effect in item.effects.iter() {
        effect_events.send(EffectEvent {
            effect: effect.clone(),
            source: item.source,
            controller: item.controller,
            targets: item.targets.clone(),
        });
    }
    
    // Clear currently resolving
    stack.currently_resolving = None;
    
    // Check for triggered abilities that happened during resolution
    // ...
}
}

Priority System

The priority system determines which player can take actions at any given time. Priority passes in turn order, starting with the active player.

Priority Implementation

#![allow(unused)]
fn main() {
#[derive(Resource)]
pub struct PrioritySystem {
    pub current_player: Entity,
    pub passed_players: HashSet<Entity>,
    pub active: bool,
}

#[derive(Event)]
pub struct PriorityEvent {
    pub player: Entity,
    pub action: PriorityAction,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PriorityAction {
    Receive,
    Pass,
    TakeAction,
}
}

Priority Passing System

#![allow(unused)]
fn main() {
pub fn handle_priority(
    mut commands: Commands,
    mut priority: ResMut<PrioritySystem>,
    mut priority_events: EventReader<PriorityEvent>,
    game_state: Res<GameState>,
    stack: Res<Stack>,
) {
    for event in priority_events.iter() {
        match event.action {
            PriorityAction::Pass => {
                // Record that this player passed
                priority.passed_players.insert(event.player);
                
                // Determine next player
                let next_player = get_next_player_in_turn_order(event.player, &game_state);
                
                // Check if all players have passed
                if priority.passed_players.len() == game_state.player_order.len() {
                    // Resolve top of stack or advance phase
                    if !stack.items.is_empty() {
                        // Resolve top of stack
                        commands.add(resolve_stack_command());
                    } else {
                        // Advance to next phase
                        commands.add(advance_phase_command());
                    }
                    
                    // Reset priority system
                    priority.passed_players.clear();
                    priority.current_player = game_state.active_player;
                } else {
                    // Pass priority to next player
                    priority.current_player = next_player;
                }
            },
            PriorityAction::TakeAction => {
                // Clear passed players since someone took an action
                priority.passed_players.clear();
                
                // After an action, active player gets priority
                priority.current_player = game_state.active_player;
            },
            // Other priority actions...
        }
    }
}
}

Special Rules

Mana Abilities

Mana abilities don't use the stack and resolve immediately, meaning they cannot be responded to. This is handled separately from the regular stack system.

Split Second

Some cards have the "Split Second" ability, which means that while they're on the stack, players can't cast spells or activate abilities that aren't mana abilities.

Interrupts and Special Timing

Certain effects can interrupt the normal flow of gameplay, such as:

• Replacement effects
• Prevention effects
• State-based actions
• Special actions that don't use the stack

Format Extensions

Different formats may extend or modify the basic stack system:

• Commander Format: May have format-specific timing rules
• Multiplayer Formats: Must handle priority passing among multiple players

For format-specific stack and priority mechanics, see the respective format documentation.

Next: Stack Resolution

Stack Resolution

This document details the implementation of the stack resolution process in Rummage, explaining how spells and abilities on the stack are processed and resolved.

Resolution Overview

Stack resolution follows the Last-In-First-Out (LIFO) principle. When all players pass priority in succession without taking any actions, the top item on the stack resolves. This process requires careful handling of various card effects, targets, and game state changes.

Resolution Process

1. Prepare for Resolution

The system begins by taking the top item off the stack and preparing it for resolution:

#![allow(unused)]
fn main() {
fn prepare_for_resolution(stack: &mut Stack, world: &mut World) -> Option<StackItem> {
    if stack.items.is_empty() {
        return None;
    }
    
    // Remove the top item from the stack
    let item = stack.items.pop().unwrap();
    
    // Store the currently resolving item for reference
    stack.currently_resolving = Some(item.clone());
    
    Some(item)
}
}

2. Check Targets

Before resolution, the system verifies that all targets are still legal:

#![allow(unused)]
fn main() {
fn verify_targets(item: &StackItem, world: &World) -> bool {
    let mut all_targets_legal = true;
    
    for target in &item.targets {
        if !is_legal_target(target, item, world) {
            all_targets_legal = false;
            break;
        }
    }
    
    all_targets_legal
}
}

If a spell or ability has no legal targets remaining, it is countered by game rules:

#![allow(unused)]
fn main() {
if !verify_targets(&item, world) {
    if item.item_type.is_spell() {
        // Counter the spell
        events.send(SpellCounteredEvent {
            spell_id: item.id,
            countered_by: CounterReason::IllegalTargets,
        });
        
        // Move spell card to graveyard
        zone_transitions.send(ZoneTransitionEvent {
            entity: item.source,
            from: Zone::Stack,
            to: Zone::Graveyard,
            cause: ZoneTransitionCause::Countered,
        });
    } else {
        // Counter the ability
        events.send(AbilityCounteredEvent {
            ability_id: item.id,
            countered_by: CounterReason::IllegalTargets,
        });
    }
    
    return;
}
}

3. Process Spell Resolution

For spell resolution, the system handles different card types appropriately:

#![allow(unused)]
fn main() {
fn resolve_spell(item: &StackItem, world: &mut World, events: &mut EventWriter<ZoneTransitionEvent>) {
    match item.item_type {
        StackItemType::Spell(CardType::Creature) |
        StackItemType::Spell(CardType::Artifact) |
        StackItemType::Spell(CardType::Enchantment) |
        StackItemType::Spell(CardType::Planeswalker) |
        StackItemType::Spell(CardType::Land) => {
            // Permanent spells - move to battlefield
            events.send(ZoneTransitionEvent {
                entity: item.source,
                from: Zone::Stack,
                to: Zone::Battlefield,
                cause: ZoneTransitionCause::Resolved,
            });
        },
        StackItemType::Spell(CardType::Instant) |
        StackItemType::Spell(CardType::Sorcery) => {
            // Non-permanent spells - move to graveyard
            events.send(ZoneTransitionEvent {
                entity: item.source,
                from: Zone::Stack,
                to: Zone::Graveyard,
                cause: ZoneTransitionCause::Resolved,
            });
        },
        _ => {} // Handle other card types
    }
}
}

4. Process Ability Resolution

For ability resolution, the system processes the effects without zone transitions:

#![allow(unused)]
fn main() {
fn resolve_ability(item: &StackItem, world: &mut World) {
    // Abilities don't change zones, only their effects are processed
    match item.item_type {
        StackItemType::Ability(AbilityType::Activated) |
        StackItemType::Ability(AbilityType::Triggered) => {
            // Process ability effects
        },
        _ => {} // Handle other ability types
    }
}
}

5. Apply Effects

The system processes each effect of the resolving item:

#![allow(unused)]
fn main() {
fn apply_effects(
    item: &StackItem, 
    world: &mut World,
    effect_events: &mut EventWriter<EffectEvent>
) {
    for effect in &item.effects {
        effect_events.send(EffectEvent {
            effect: effect.clone(),
            source: item.source,
            controller: item.controller,
            targets: item.targets.clone(),
        });
    }
}
}

6. Post-Resolution Cleanup

After resolution, the system clears the currently resolving item and checks for triggered abilities:

#![allow(unused)]
fn main() {
fn post_resolution_cleanup(stack: &mut Stack, world: &mut World) {
    // Clear the currently resolving item
    stack.currently_resolving = None;
    
    // Process pending triggers that occurred during resolution
    for trigger in stack.pending_triggers.drain(..) {
        world.spawn_trigger(trigger);
    }
    
    // Check state-based actions
    check_state_based_actions(world);
    
    // Return priority to active player
    set_priority(world.resource::<GameState>().active_player, world);
}
}

Special Resolution Cases

Countering Spells and Abilities

When a spell or ability is countered, it never resolves:

#![allow(unused)]
fn main() {
pub fn counter_spell_system(
    mut counter_events: EventReader<CounterSpellEvent>,
    mut stack: ResMut<Stack>,
    mut zone_transitions: EventWriter<ZoneTransitionEvent>,
) {
    for event in counter_events.iter() {
        // Find the spell on the stack
        if let Some(index) = stack.items.iter().position(|item| item.id == event.target) {
            // Remove it from the stack
            let item = stack.items.remove(index);
            
            // Move the card to graveyard
            zone_transitions.send(ZoneTransitionEvent {
                entity: item.source,
                from: Zone::Stack,
                to: Zone::Graveyard,
                cause: ZoneTransitionCause::Countered,
            });
        }
    }
}
}

Split Second

When resolving items with Split Second, special handling prevents responses:

#![allow(unused)]
fn main() {
pub fn check_split_second(stack: &Stack) -> bool {
    stack.items.iter().any(|item| {
        if let StackItemType::Spell(card_type) = &item.item_type {
            // Check if any spell on the stack has split second
            let has_split_second = world
                .get::<Card>(item.source)
                .map(|card| card.has_ability(Ability::SplitSecond))
                .unwrap_or(false);
                
            return has_split_second;
        }
        false
    })
}
}

Integration with Other Systems

The stack resolution process integrates with:

1. Zone System: Moving cards between zones after resolution
2. Effect System: Processing the effects of spells and abilities
3. Targeting System: Verifying target legality
4. Trigger System: Handling triggers that occur during resolution
5. State-Based Action System: Checking state-based actions after resolution

Implementation Status

The stack resolution implementation currently:

• ✅ Handles basic spell and ability resolution
• ✅ Processes spell types correctly (permanent vs. non-permanent)
• ✅ Validates targets before resolution
• ✅ Implements spell countering
• ✅ Supports triggered abilities that trigger during resolution
• 🔄 Handling complex resolution effects (choices, conditions, etc.)
• 🔄 Implementing special cases like Split Second

Next: Priority System

State-Based Actions in MTG

Overview

State-Based Actions (SBAs) are one of the foundational mechanisms of Magic: The Gathering's rules system. They serve as automatic checks that the game performs regularly to ensure game rules are properly enforced without requiring explicit player actions. These checks occur whenever a player would receive priority and before any player actually receives priority.

Core Functionality

State-based actions handle many crucial game state validations:

• Player loss conditions:

  • A player with 0 or less life loses the game
  • A player attempting to draw from an empty library loses the game
  • A player with 10 or more poison counters loses the game (in formats where poison counters are relevant)

• Creature conditions:

  • Creatures with toughness 0 or less are put into their owner's graveyard
  • Creatures with damage marked on them greater than or equal to their toughness are destroyed
  • Creatures that have been dealt damage by a source with deathtouch are destroyed

• Permanent-specific rules:

  • Planeswalker with no loyalty counters is put into its owner's graveyard
  • Auras that aren't attached to anything or attached illegally are put into their owner's graveyard
  • Equipment or Fortifications that are attached illegally become unattached
  • Legendary permanents with the same name are put into their owner's graveyard except the most recently played one

• Token and counter rules:

  • A token that has left the battlefield ceases to exist
  • If a permanent has both +1/+1 and -1/-1 counters on it, they cancel out in pairs

Implementation

The state-based actions system is implemented as a collection of systems that run between steps and phases:

#![allow(unused)]
fn main() {
#[derive(Resource)]
pub struct StateBasedActionSystem {
    // Configuration for SBA processing
    pub enabled: bool,
    pub last_check_time: Duration,
    pub check_frequency: Duration,
    
    // Tracking for specific SBAs
    pub pending_legendary_checks: Vec<Entity>,
    pub pending_destruction: Vec<Entity>,
    pub pending_life_checks: Vec<Entity>,
}

// Systems that implement specific checks
pub fn check_player_loss_conditions(/* ... */);
pub fn check_creature_destruction(/* ... */);
pub fn check_attachment_validity(/* ... */);
pub fn check_legendary_rule(/* ... */);
pub fn check_token_existence(/* ... */);
pub fn check_counter_interactions(/* ... */);
}

Application Order

State-based actions are applied in a specific order, but all applicable state-based actions are performed simultaneously as a single event. If performing state-based actions creates new conditions for state-based actions, those new state-based actions will be checked in the next round of checks.

This is especially important for situations like:

• A player at 0 life with a creature dying simultaneously
• Multiple legendary permanents entering the battlefield at the same time
• Creatures with damage marked receiving -X/-X effects

Multiplayer Considerations

In multiplayer games:

• State-based actions are checked simultaneously for all players and permanents
• When a player leaves the game, all cards they own leave the game
• Objects controlled by a player who left the game are exiled, unless they're controlled by a different player's ongoing effect

Optimization in Rummage

The SBA system in Rummage is optimized to:

• Only check relevant game objects (using spatial partitioning where appropriate)
• Use efficient data structures to track pending actions
• Batch similar checks where possible
• Cache results when appropriate
• Minimize performance impact during complex game states

Related Documentation

• Turn Structure: When state-based actions are checked during the turn
• Zones: How state-based actions interact with game zones
• Combat: Combat-specific state-based actions

Combat System

Overview

The Combat system is a fundamental part of Magic: The Gathering, implemented in Rummage according to the comprehensive rules. This section documents the core combat mechanics that apply to all formats.

Combat Phases

A combat phase consists of the following steps in order:

1. Beginning of Combat Step - The last chance for players to cast spells or activate abilities before attackers are declared
2. Declare Attackers Step - The active player chooses which creatures will attack and which opponents or planeswalkers they will attack
3. Declare Blockers Step - Each defending player chooses which creatures will block and which attacking creatures they will block
4. Combat Damage Step - Combat damage is assigned and dealt (with separate first strike and regular damage steps if needed)
5. End of Combat Step - The last chance for players to cast spells or activate abilities before the combat phase ends

Core Combat Mechanics

Attacking

• Only untapped creatures can be declared as attackers
• Creatures can't attack their controller
• Creatures can attack players or planeswalkers (unless modified by card effects)
• Creatures with Defender can't attack
• Creatures with Summoning Sickness (entered battlefield this turn) can't attack unless they have Haste

Blocking

• Tapped creatures can't block
• Each blocking creature can only block one attacker (unless modified by card effects)
• Multiple creatures can block a single attacker
• Creatures can only block attackers that are attacking their controller or planeswalkers controlled by their controller

Combat Damage

• Attacking creatures deal damage equal to their power
• Blocking creatures deal damage equal to their power
• If multiple creatures block a single attacker, the attacker's controller assigns the damage among them
• Combat damage is dealt simultaneously (unless first strike or double strike is involved)
• Combat damage to players causes life loss
• Combat damage to planeswalkers removes loyalty counters
• Combat damage to creatures causes damage marked on them

Special Combat Abilities

• First Strike: Creatures with first strike deal combat damage before creatures without first strike
• Double Strike: Creatures with double strike deal damage in both the first strike and regular damage steps
• Trample: Excess combat damage can be assigned to the defending player or planeswalker
• Vigilance: Creatures with vigilance don't tap when attacking
• Deathtouch: Any amount of damage from a creature with deathtouch is enough to destroy the damaged creature
• Lifelink: Damage dealt by a creature with lifelink causes its controller to gain that much life

Implementation Details

The combat system is implemented through a series of components and systems that manage the state of creatures in combat, process combat events, and enforce the rules of combat.

Extensions for Formats

Different formats may extend or modify these core combat mechanics:

• Commander Format: Adds commander damage tracking
• Two-Headed Giant: Modifies how creatures can attack and block
• Planechase: May add special combat rules based on the current plane

For format-specific extensions like Commander's combat rules, see the respective format documentation.

Combat Documentation

• Combat Phases - Detailed explanation of each combat step
• First Strike and Double Strike - How these abilities modify combat
• Combat Damage Calculation - Rules for damage assignment and resolution

Combat Phases

Overview

The combat phase in Magic: The Gathering is divided into five distinct steps, each with specific rules and opportunities for player interaction. This document details how these steps are implemented in Rummage's core engine.

Beginning of Combat Step

The Beginning of Combat step marks the start of the combat phase. During this step:

1. "At the beginning of combat" triggered abilities go on the stack
2. Players receive priority, starting with the active player
3. This is the last opportunity to use effects that would prevent creatures from attacking

Implementation

#![allow(unused)]
fn main() {
pub fn beginning_of_combat_system(
    mut commands: Commands,
    game_state: Res<GameState>,
    mut phase_events: EventWriter<BeginningOfCombatEvent>,
    mut triggered_abilities: EventWriter<TriggeredAbilityEvent>,
) {
    // Generate beginning of combat event
    phase_events.send(BeginningOfCombatEvent {
        active_player: game_state.active_player,
    });
    
    // Check for triggered abilities that trigger at beginning of combat
    // Add them to the stack
    // ...
}
}

Declare Attackers Step

During the Declare Attackers step:

1. The active player declares attackers
2. Creatures attack as a group
3. The active player taps attacking creatures (unless they have vigilance)
4. "Whenever a creature attacks" triggered abilities go on the stack
5. Players receive priority, starting with the active player

Attacking Rules

• Only untapped creatures controlled by the active player can be declared as attackers
• Each attacking creature must attack either an opponent or a planeswalker an opponent controls
• Creatures with summoning sickness can't attack unless they have haste
• Attacking doesn't use the stack and can't be responded to directly

Implementation

#![allow(unused)]
fn main() {
pub fn declare_attackers_system(
    mut commands: Commands,
    mut game_state: ResMut<GameState>,
    mut attack_events: EventReader<DeclareAttackEvent>,
    mut creatures: Query<(Entity, &mut Creature, &Controller)>,
    mut triggered_abilities: EventWriter<TriggeredAbilityEvent>,
) {
    // Process attack declarations
    for attack_event in attack_events.iter() {
        // Validate attackers (untapped, controlled by active player, etc.)
        // Record which creatures are attacking and what they're attacking
        // Tap attacking creatures without vigilance
        // ...
    }
    
    // Generate triggered abilities for "whenever a creature attacks"
    // ...
}
}

Declare Blockers Step

During the Declare Blockers step:

1. The defending player(s) declare blockers
2. Each blocking creature must block exactly one attacking creature
3. "Whenever a creature blocks" triggered abilities go on the stack
4. The active player declares the damage assignment order for creatures blocked by multiple creatures
5. Players receive priority, starting with the active player

Blocking Rules

• Only untapped creatures can block
• Each creature can block only one attacker (unless it has special abilities)
• Multiple creatures can block a single attacker
• Blocking doesn't use the stack and can't be responded to directly

Implementation

#![allow(unused)]
fn main() {
pub fn declare_blockers_system(
    mut commands: Commands,
    mut game_state: ResMut<GameState>,
    mut block_events: EventReader<DeclareBlockEvent>,
    mut creatures: Query<(Entity, &Creature, &Controller)>,
    mut triggered_abilities: EventWriter<TriggeredAbilityEvent>,
) {
    // Process block declarations
    for block_event in block_events.iter() {
        // Validate blockers (untapped, etc.)
        // Record which creatures are blocking and what they're blocking
        // ...
    }
    
    // Generate triggered abilities for "whenever a creature blocks" or "becomes blocked"
    // ...
    
    // Determine damage assignment order for multiple blockers
    // ...
}
}

Combat Damage Step

During the Combat Damage step:

1. If any creatures have first strike or double strike, a separate First Strike Combat Damage step occurs first
2. The active player assigns combat damage from their attacking creatures
3. The defending player(s) assign combat damage from their blocking creatures
4. All combat damage is dealt simultaneously
5. Players receive priority, starting with the active player

Damage Assignment Rules

• Each attacking creature assigns damage equal to its power
• Each blocking creature assigns damage equal to its power
• Blocked creatures assign their damage to the blocking creatures
• Unblocked creatures assign their damage to the player or planeswalker they're attacking
• If multiple creatures block an attacker, the attacker's controller decides how to distribute the damage

Implementation

#![allow(unused)]
fn main() {
pub fn combat_damage_system(
    mut commands: Commands,
    game_state: Res<GameState>,
    combat_state: Res<CombatState>,
    mut creatures: Query<(Entity, &Creature, &mut Health)>,
    mut players: Query<(Entity, &Player, &mut Life)>,
    mut planeswalkers: Query<(Entity, &Planeswalker, &mut Loyalty)>,
) {
    // Handle first strike damage if needed
    // ...
    
    // Assign and deal combat damage
    for (attacker, targets) in combat_state.attackers.iter() {
        // Calculate damage amount
        // Apply damage to appropriate targets
        // Handle special abilities (deathtouch, lifelink, etc.)
        // ...
    }
    
    // Check for state-based actions after damage
    // ...
}
}

End of Combat Step

During the End of Combat step:

1. "At end of combat" triggered abilities go on the stack
2. Players receive priority, starting with the active player
3. After this step, all creatures and planeswalkers are removed from combat

Implementation

#![allow(unused)]
fn main() {
pub fn end_of_combat_system(
    mut commands: Commands,
    game_state: Res<GameState>,
    mut combat_state: ResMut<CombatState>,
    mut phase_events: EventWriter<EndOfCombatEvent>,
    mut triggered_abilities: EventWriter<TriggeredAbilityEvent>,
) {
    // Generate end of combat event
    phase_events.send(EndOfCombatEvent {
        active_player: game_state.active_player,
    });
    
    // Check for triggered abilities that trigger at end of combat
    // ...
    
    // Remove all creatures from combat
    combat_state.attackers.clear();
    combat_state.blockers.clear();
    // ...
}
}

Format-Specific Extensions

Different MTG formats may extend these basic combat phases with additional rules:

• Commander: Tracks commander damage separately
• Two-Headed Giant: Modifies how combat damage is dealt to players
• Multiplayer Formats: Have special rules for attacking multiple opponents

For details on format-specific combat mechanics, see the respective format documentation.

Next: First Strike and Double Strike

First Strike and Double Strike

Overview

First Strike and Double Strike are two of the most important keyword abilities in Magic: The Gathering that modify how creatures deal combat damage. They create a special combat damage step that occurs before the regular combat damage step.

First Strike

First Strike allows creatures to deal combat damage before creatures without First Strike.

Rules

• Creatures with First Strike deal damage in the "first strike combat damage step" which happens before the regular combat damage step
• Creatures without First Strike or Double Strike don't deal or receive combat damage in this step
• If no creatures with First Strike or Double Strike are involved in combat, this step is skipped entirely
• First Strike doesn't provide any additional advantage in creature-to-creature combat outside of combat damage timing

Implementation

#![allow(unused)]
fn main() {
#[derive(Component)]
pub struct FirstStrike;

pub fn handle_first_strike_damage(
    combat_state: Res<CombatState>,
    creatures: Query<(Entity, &Creature, &Attack, &BlockedBy, Option<&FirstStrike>, Option<&DoubleStrike>)>,
    mut health: Query<&mut Health>,
    mut damage_events: EventWriter<DamageEvent>,
) {
    // Identify creatures with First Strike or Double Strike
    let first_strikers = creatures.iter()
        .filter(|(_, _, _, _, first_strike, double_strike)| 
            first_strike.is_some() || double_strike.is_some());
            
    // Process First Strike damage
    for (entity, creature, attack, blocked_by, _, _) in first_strikers {
        // Calculate and assign damage
        // ...
    }
}
}

Double Strike

Double Strike combines the benefits of First Strike with the ability to deal damage again in the regular combat damage step.

Rules

• Creatures with Double Strike deal combat damage in both the first strike combat damage step AND the regular combat damage step
• This effectively allows them to deal twice their power in damage during combat
• If a Double Strike creature is removed from combat after the first strike step (e.g., by being destroyed), it won't deal damage in the regular step
• Double Strike doesn't increase the amount of damage dealt in each individual step - it allows the creature to deal damage in both steps

Implementation

#![allow(unused)]
fn main() {
#[derive(Component)]
pub struct DoubleStrike;

pub fn handle_regular_combat_damage(
    combat_state: Res<CombatState>,
    creatures: Query<(Entity, &Creature, &Attack, &BlockedBy, Option<&DoubleStrike>)>,
    mut health: Query<&mut Health>,
    mut damage_events: EventWriter<DamageEvent>,
) {
    // Process Regular Combat Damage
    for (entity, creature, attack, blocked_by, _) in creatures.iter() {
        // All creatures without First Strike always deal damage here
        // Creatures with Double Strike also deal damage here
        // ...
    }
}
}

Interactions with Other Abilities

First Strike and Double Strike interact with other combat abilities in specific ways:

• Deathtouch: A creature with both First Strike/Double Strike and Deathtouch can destroy blocking/blocked creatures before they deal damage
• Lifelink: A creature with both Double Strike and Lifelink will cause its controller to gain life twice
• Trample: A creature with both First Strike/Double Strike and Trample can deal excess damage to players in both damage steps

Example Combat Scenarios

First Strike vs. Non-First Strike

When a 2/2 creature with First Strike blocks or is blocked by a 2/2 creature without First Strike:

1. First Strike creature deals 2 damage in the first strike damage step
2. The other creature is destroyed before it can deal damage in the regular damage step

Double Strike vs. Regular Creature

When a 2/2 creature with Double Strike blocks or is blocked by a 3/3 creature without First Strike:

1. Double Strike creature deals 2 damage in the first strike damage step
2. The 3/3 creature survives with 1 toughness remaining
3. Both creatures deal damage in the regular damage step (2 more from Double Strike, 3 from the regular creature)
4. Both creatures are destroyed

Related Documentation

• Combat Phases
• Combat Damage Calculation

Combat Damage Calculation

Overview

Combat damage calculation is a critical aspect of the Magic: The Gathering combat system. This document explains how damage is calculated, assigned, and applied during combat in Rummage's implementation.

Damage Assignment

Basic Rules

1. Each attacking or blocking creature assigns combat damage equal to its power
2. Attacking creatures that aren't blocked assign their damage to the player or planeswalker they're attacking
3. Blocking creatures assign their damage to the creature they're blocking
4. Blocked creatures assign their damage to the creatures blocking them

Multiple Blockers

When multiple creatures block a single attacker:

1. The attacking player puts the blocking creatures in a damage assignment order
2. The attacker must assign at least lethal damage to each creature in the order before assigning damage to the next creature
3. "Lethal damage" is damage equal to the creature's toughness minus damage already marked on it

#![allow(unused)]
fn main() {
pub fn determine_damage_assignment_order(
    mut commands: Commands,
    mut combat_state: ResMut<CombatState>,
    blocker_groups: Query<(&Creature, &Health, &Blocking)>,
) {
    for (attacker_entity, blockers) in combat_state.blockers_per_attacker.iter() {
        if blockers.len() > 1 {
            // Request damage assignment order from attacking player
            // Store the order in the combat state
            // ...
        }
    }
}
}

Damage Application

Once damage is assigned, it is applied simultaneously:

1. Damage to creatures is marked on them but doesn't immediately reduce toughness
2. Damage to players reduces their life total
3. Damage to planeswalkers removes loyalty counters
4. Special abilities like deathtouch and lifelink take effect at this time

#![allow(unused)]
fn main() {
pub fn apply_combat_damage(
    combat_state: Res<CombatState>,
    mut creatures: Query<(Entity, &Creature, &mut Health)>,
    mut players: Query<(Entity, &Player, &mut Life)>,
    mut planeswalkers: Query<(Entity, &Planeswalker, &mut Loyalty)>,
    mut damage_events: EventWriter<DamageEvent>,
) {
    // Calculate and apply damage from all sources
    // ...
    
    // For creatures
    for (target, damage_amount) in creature_damage.iter() {
        if let Ok((_, _, mut health)) = creatures.get_mut(*target) {
            health.marked_damage += *damage_amount;
            // Generate damage event
            damage_events.send(DamageEvent {
                source: source_entity,
                target: *target,
                amount: *damage_amount,
                is_combat_damage: true,
            });
        }
    }
    
    // For players and planeswalkers (similar logic)
    // ...
}
}

Special Damage Considerations

Deathtouch

Deathtouch modifies damage assignment rules:

• Any amount of damage from a source with deathtouch is considered lethal damage
• When assigning damage from an attacker with deathtouch to multiple blockers, only 1 damage needs to be assigned to each creature before moving to the next

Trample

Trample allows excess damage to be assigned to the player or planeswalker:

• The attacker must still assign lethal damage to all blockers
• Any remaining damage can be assigned to the defending player or planeswalker
• If all blocking creatures are removed from combat, all damage is assigned to the player or planeswalker

#![allow(unused)]
fn main() {
pub fn handle_trample_damage(
    combat_state: Res<CombatState>,
    creatures: Query<(Entity, &Creature, &Attack, Option<&Trample>)>,
    blockers: Query<(Entity, &Creature, &Health, &Blocking)>,
    mut player_damage: ResMut<HashMap<Entity, u32>>,
) {
    for (attacker, creature, attack, trample) in creatures.iter() {
        if trample.is_some() {
            // Calculate how much damage is needed for blockers
            // Assign excess to the player or planeswalker
            // ...
        }
    }
}
}

Protection and Prevention

Some effects modify how damage is dealt or received:

• Protection prevents damage from sources with specific characteristics
• Prevention effects can replace some or all damage that would be dealt
• These effects are applied during damage calculation, before damage is actually dealt

Damage Resolution

After combat damage is dealt, the game checks for state-based actions:

1. Creatures with lethal damage are destroyed
2. Players with 0 or less life lose the game
3. Planeswalkers with 0 loyalty counters are put into their owner's graveyard

#![allow(unused)]
fn main() {
pub fn check_combat_damage_results(
    creatures: Query<(Entity, &Creature, &Health)>,
    players: Query<(Entity, &Player, &Life)>,
    planeswalkers: Query<(Entity, &Planeswalker, &Loyalty)>,
    mut destroy_events: EventWriter<DestroyPermanentEvent>,
    mut player_loss_events: EventWriter<PlayerLossEvent>,
) {
    // Check for destroyed creatures
    for (entity, _, health) in creatures.iter() {
        if health.marked_damage >= health.toughness {
            destroy_events.send(DestroyPermanentEvent {
                entity: entity,
                reason: DestructionReason::LethalDamage,
            });
        }
    }
    
    // Check for player losses and planeswalker destruction
    // ...
}
}

Related Documentation

• Combat Phases
• First Strike and Double Strike

Abilities

This document outlines the different types of abilities in Magic: The Gathering as implemented in Rummage.

Types of Abilities

Magic: The Gathering has three main types of abilities:

1. Activated Abilities: Abilities a player can activate by paying a cost
2. Triggered Abilities: Abilities that trigger automatically when a specific event occurs
3. Static Abilities: Abilities that modify the game rules or create continuous effects

Activated Abilities

Activated abilities are written in the format: "Cost: Effect." Examples include:

• "{T}: Add {G}." (A basic Forest's mana ability)
• "{2}{W}, {T}: Create a 1/1 white Soldier creature token."
• "{B}, Pay 2 life: Draw a card."

Implementation

In Rummage, activated abilities are implemented as follows:

#![allow(unused)]
fn main() {
pub struct ActivatedAbility {
    pub activation_cost: Cost,
    pub effect: AbilityEffect,
    pub timing_restriction: Option<TimingRestriction>,
    pub target_requirement: Option<TargetRequirement>,
}

pub enum Cost {
    Mana(ManaCost),
    Tap,
    PayLife(u32),
    SacrificeThis,
    SacrificePermanent(PermanentType),
    Discard(DiscardRequirement),
    Exile(ExileRequirement),
    Multiple(Vec<Cost>),
    // Other cost types...
}
}

Mana Abilities

A special subcategory of activated abilities, mana abilities:

• Produce mana
• Don't target
• Don't use the stack
• Resolve immediately

Triggered Abilities

Triggered abilities use the words "when," "whenever," or "at." Examples include:

• "When this creature enters the battlefield, draw a card."
• "Whenever a creature dies, gain 1 life."
• "At the beginning of your upkeep, draw a card."

Implementation

In Rummage, triggered abilities are implemented with:

#![allow(unused)]
fn main() {
pub struct TriggeredAbility {
    pub trigger_condition: TriggerCondition,
    pub effect: AbilityEffect,
    pub target_requirement: Option<TargetRequirement>,
}

pub enum TriggerCondition {
    EntersBattlefield(FilterType),
    LeavesBattlefield(FilterType),
    CastSpell(FilterType),
    BeginningOfPhase(Phase),
    EndOfPhase(Phase),
    CreatureDies(FilterType),
    DamageDealt(DamageFilter),
    // Other trigger conditions...
}
}

Trigger Types

There are several types of triggers:

• State triggers: "When/Whenever [state] is true..."
• Event triggers: "When/Whenever [event] occurs..."
• Phase/step triggers: "At the beginning of [phase/step]..."

Static Abilities

Static abilities apply continuously and don't use the stack. Examples include:

• "Creatures you control get +1/+1."
• "Opponent's spells cost {1} more to cast."
• "You have hexproof."

Implementation

In Rummage, static abilities are implemented as follows:

#![allow(unused)]
fn main() {
pub struct StaticAbility {
    pub effect: StaticEffect,
    pub condition: Option<Condition>,
}

pub enum StaticEffect {
    ModifyPowerToughness(PTModification),
    ModifyCost(CostModification),
    GrantKeyword(KeywordGrant),
    PreventActions(ActionPrevention),
    ReplaceEffect(ReplacementEffect),
    // Other static effects...
}
}

Layering System

Static abilities that modify characteristics are applied in a specific order defined by the "layer system":

1. Copy effects
2. Control-changing effects
3. Text-changing effects
4. Type-changing effects
5. Color-changing effects
6. Ability-adding/removing effects
7. Power/toughness changing effects

Keyword Abilities

Keyword abilities are shorthand for common abilities:

• Flying: "This creature can only be blocked by creatures with flying or reach."
• Haste: "This creature can attack and use {T} abilities as soon as it comes under your control."
• Deathtouch: "Any amount of damage this deals to a creature is enough to destroy it."
• Trample: "This creature can deal excess combat damage to the player or planeswalker it's attacking."

Implementation

In Rummage, keyword abilities are implemented as:

#![allow(unused)]
fn main() {
pub enum KeywordAbility {
    Flying,
    Haste,
    Vigilance,
    Trample,
    FirstStrike,
    DoubleStrike,
    Deathtouch,
    Lifelink,
    Reach,
    Hexproof,
    Indestructible,
    // Other keywords...
}
}

Loyalty Abilities

Planeswalkers have loyalty abilities, a special type of activated ability:

• "+1: Draw a card."
• "-2: Create a 3/3 Beast creature token."
• "-8: You get an emblem with 'Creatures you control get +2/+2.'"

Implementation

Loyalty abilities are implemented as:

#![allow(unused)]
fn main() {
pub struct LoyaltyAbility {
    pub cost: i32, // Positive or negative loyalty change
    pub effect: AbilityEffect,
    pub target_requirement: Option<TargetRequirement>,
}
}

Implementation Status

The ability implementation status is:

• ✅ Basic activated abilities
• ✅ Mana abilities
• ✅ Common keyword abilities
• 🔄 Complex triggered abilities
• 🔄 Replacement effects
• 🔄 Layering system
• ✅ Loyalty abilities

Related Documentation

• Targeting: How abilities target
• Stack: How abilities use the stack
• Mana and Costs: How ability costs work

Casting Spells

This document outlines the rules for casting spells in Magic: The Gathering as implemented in Rummage.

Spell Casting Process

Casting a spell in Magic: The Gathering follows a specific sequence of steps:

1. Announce the Spell: The player announces they are casting a spell and places it on the stack.
2. Choose Modes: If the spell is modal, the player chooses which mode(s) to use.
3. Choose Targets: If the spell requires targets, the player chooses legal targets.
4. Choose Division of Effects: For spells that divide their effect, the player chooses how to divide it.
5. Choose how to pay X: For spells with X in their cost, the player chooses the value of X.
6. Determine Total Cost: Calculate the total cost, including additional or alternative costs.
7. Activate Mana Abilities: The player activates mana abilities to generate mana.
8. Pay Costs: The player pays all costs in any order.

After these steps, the spell is considered cast and is placed on the stack. It will resolve when all players pass priority in succession.

Implementation Details

In Rummage, spell casting is implemented using a state machine approach that guides the player through each step:

#![allow(unused)]
fn main() {
pub enum SpellCastingState {
    NotCasting,
    AnnouncingSpell,
    ChoosingModes,
    ChoosingTargets,
    DividingEffects,
    ChoosingX,
    CalculatingCost,
    GeneratingMana,
    PayingCosts,
    Completed,
}

pub struct SpellCasting {
    pub state: SpellCastingState,
    pub spell_entity: Option<Entity>,
    pub casting_player: Entity,
    pub modes_chosen: Vec<u32>,
    pub targets_chosen: Vec<TargetInfo>,
    pub divisions: Vec<u32>,
    pub x_value: u32,
    pub total_cost: ManaCost,
    pub paid_mana: Vec<ManaPayment>,
}
}

Types of Spells

Magic: The Gathering has several types of spells:

Permanent Spells

These become permanents on the battlefield when they resolve:

• Creature spells
• Artifact spells
• Enchantment spells
• Planeswalker spells
• Land cards (technically not spells)

Non-Permanent Spells

These go to the graveyard when they resolve:

• Instant spells
• Sorcery spells

Timing Restrictions

Different spell types have different timing restrictions:

• Instant: Can be cast at any time when a player has priority
• Sorcery: Can only be cast during a player's main phase when the stack is empty and they have priority
• Other spell types: Generally follow sorcery timing, with exceptions based on abilities

Special Cases

Split Cards

Split cards have two halves, and the player chooses which half to cast or may cast both halves with Fuse.

Modal Spells

Modal spells allow the player to choose from multiple effects, with the number of choices often specified on the card.

Spells with X in the Cost

The player chooses a value for X, which affects both the spell's cost and its effect.

Alternative Costs

Some spells offer alternative ways to cast them, such as:

• Flashback
• Overload
• Foretell
• Adventure

UI Integration

The spell casting process integrates with the UI through:

1. Card Selection: Players select a card to begin casting
2. Target Selection: Visual interface for selecting targets
3. Cost Payment: Interface for choosing which mana to pay
4. Mode Selection: Interface for choosing modes for modal spells

For more on the UI implementation, see Card Selection.

Implementation Status

The spell casting implementation is:

• ✅ Basic spell casting
• ✅ Cost calculation
• ✅ Target selection
• ✅ Mana payment
• 🔄 Alternative costs
• 🔄 Complex modal spells
• ✅ X spells

Related Documentation

• Stack: How spells interact with the stack
• Mana and Costs: Details on mana costs and payment
• Targeting: Rules for selecting targets

ECS Implementation of MTG Rules

This document explains how Magic: The Gathering rules are implemented using Bevy's Entity Component System (ECS) architecture in Rummage.

Table of Contents

1. Introduction
2. Entity Representations
3. Component Design
4. System Organization
5. Event-Driven Mechanics
6. Example Implementations

Introduction

Bevy's Entity Component System (ECS) architecture provides an ideal foundation for implementing Magic: The Gathering's complex rule system. This architecture offers several key advantages:

• Data-Logic Separation: Game data (components) remains separate from game logic (systems)
• Parallelism: Game mechanics can process in parallel where possible
• Composition: Entities are composed of reusable components rather than inheritance hierarchies
• Extensibility: New functionality can be added without modifying existing code

These benefits directly address the challenges of implementing MTG's intricate, interconnected rule system in a maintainable, testable, and performant way.

Entity Representations

In Rummage, we model the core MTG game elements as entities with specific components:

Cards

Cards are represented as entities with components describing their characteristics:

#![allow(unused)]
fn main() {
// Core card identity
#[derive(Component)]
struct Card {
    id: String,
    oracle_id: Uuid,
}

// Name component (separate for query efficiency)
#[derive(Component)]
struct CardName(String);

// Card type component
#[derive(Component)]
enum CardType {
    Creature,
    Instant,
    Sorcery,
    Artifact,
    Enchantment,
    Land,
    Planeswalker,
}

// Mana cost component
#[derive(Component)]
struct ManaCost {
    white: u8,
    blue: u8,
    black: u8,
    red: u8,
    green: u8,
    colorless: u8,
    generic: u8,
}

// Creature-specific components
#[derive(Component)]
struct Power(i32);

#[derive(Component)]
struct Toughness(i32);
}

Players

Players are entities with components tracking game state:

#![allow(unused)]
fn main() {
// Core player identity
#[derive(Component)]
struct Player {
    id: Uuid,
    name: String,
}

// Life total component
#[derive(Component)]
struct Life(i32);

// Mana pool component
#[derive(Component)]
struct ManaPool {
    white: u8,
    blue: u8,
    black: u8,
    red: u8,
    green: u8,
    colorless: u8,
}
}

Zones

Game zones are implemented as entities with specialized components:

#![allow(unused)]
fn main() {
// Zone type identifier
#[derive(Component)]
enum ZoneType {
    Battlefield,
    Hand,
    Library,
    Graveyard,
    Stack,
    Exile,
    Command,
}

// Container for entities in a zone
#[derive(Component)]
struct ZoneContents {
    entities: Vec<Entity>,
}

// Zone ownership
#[derive(Component)]
struct BelongsToPlayer(Entity);
}

Component Design

Our component design adheres to these core principles:

1. Single Responsibility: Each component represents one specific aspect of a game entity
2. Data-Oriented: Components store data only, not behavior
3. Minimalist: Components include only necessary data to minimize memory usage
4. Composable: Complex entities are built by combining simple components

This approach enables flexible entity composition. For example, a creature permanent on the battlefield might have:

#![allow(unused)]
fn main() {
// A creature permanent's components
Entity {
    Card { id: "c4a81753", oracle_id: "..." },
    CardName("Llanowar Elves"),
    CardType::Creature,
    Power(1),
    Toughness(1),
    InZone(ZoneType::Battlefield),
    UntappedState,
    TapForManaAbility { color: Green },
    CreatureType(vec!["Elf", "Druid"]),
    ControlledBy(player_entity),
    // Additional components for abilities, counters, etc.
}
}

System Organization

Systems implement game rules and mechanics, organized into logical categories:

Turn Structure Systems

Systems that handle the progression of game turns:

#![allow(unused)]
fn main() {
// Beginning of turn system
fn begin_turn_system(
    mut turn_state: ResMut<TurnState>,
    mut events: EventWriter<BeginTurnEvent>,
    query: Query<Entity, With<ActivePlayer>>,
) {
    if let Ok(active_player) = query.get_single() {
        events.send(BeginTurnEvent { player: active_player });
        turn_state.phase = Phase::Beginning;
        turn_state.step = Step::Untap;
    }
}

// Untap step system
fn untap_step_system(
    turn_state: Res<TurnState>,
    active_player: Query<Entity, With<ActivePlayer>>,
    mut permanents: Query<(Entity, &ControlledBy, &mut UntappedState)>,
) {
    // Skip if not in untap step
    if turn_state.phase != Phase::Beginning || turn_state.step != Step::Untap {
        return;
    }
    
    // Get active player
    let active_player = match active_player.get_single() {
        Ok(player) => player,
        Err(_) => return,
    };
    
    // Untap permanents controlled by active player
    for (_, controlled_by, mut untapped) in &mut permanents {
        if controlled_by.0 == active_player {
            *untapped = UntappedState::Untapped;
        }
    }
}
}

State-Based Actions

Systems that check and apply state-based effects:

#![allow(unused)]
fn main() {
// System for creatures with 0 or less toughness
fn check_creature_death(
    mut commands: Commands,
    creatures: Query<(Entity, &Toughness, &InZone), With<CardType::Creature>>,
    mut zone_events: EventWriter<ZoneChangeEvent>,
) {
    for (entity, toughness, zone) in &creatures {
        if toughness.0 <= 0 && zone.0 == ZoneType::Battlefield {
            // Move creature to graveyard
            zone_events.send(ZoneChangeEvent {
                entity,
                from: ZoneType::Battlefield,
                to: ZoneType::Graveyard,
                cause: ZoneChangeCause::StateBased,
            });
        }
    }
}

// System for players with 0 or less life
fn check_player_loss(
    players: Query<(Entity, &Life, &Player)>,
    mut game_events: EventWriter<GameEvent>,
) {
    for (entity, life, player) in &players {
        if life.0 <= 0 {
            game_events.send(GameEvent::PlayerLost {
                player: entity,
                reason: LossReason::ZeroLife,
            });
        }
    }
}
}

Spell Resolution

Systems for spell casting and resolution:

#![allow(unused)]
fn main() {
// Adding spells to the stack
fn cast_spell_system(
    mut commands: Commands,
    mut cast_events: EventReader<CastSpellEvent>,
    mut stack: ResMut<Stack>,
) {
    for event in cast_events.iter() {
        // Create stack object entity
        let stack_object = commands.spawn((
            StackObject,
            SourceCard(event.card),
            ControlledBy(event.controller),
            event.targets.clone(),
            // Additional stack object components
        )).id();
        
        // Add to stack
        stack.objects.push(stack_object);
    }
}

// Resolving the top object on the stack
fn resolve_top_of_stack(
    mut commands: Commands,
    mut stack: ResMut<Stack>,
    objects: Query<(Entity, &StackObject, &SourceCard, &ControlledBy)>,
    cards: Query<&CardType>,
    mut resolution_events: EventWriter<StackResolutionEvent>,
) {
    if let Some(top_object) = stack.objects.pop() {
        if let Ok((entity, _, source_card, controller)) = objects.get(top_object) {
            // Determine appropriate resolution based on card type
            if let Ok(card_type) = cards.get(source_card.0) {
                resolution_events.send(StackResolutionEvent {
                    stack_object: entity,
                    source: source_card.0,
                    controller: controller.0,
                    card_type: card_type.clone(),
                });
            }
        }
    }
}
}

Event-Driven Mechanics

MTG's reactive mechanics are implemented using Bevy's event system:

Game Events

#![allow(unused)]
fn main() {
// Card draw event
#[derive(Event)]
struct DrawCardEvent {
    player: Entity,
    amount: usize,
}

// Damage event
#[derive(Event)]
struct DamageEvent {
    source: Entity,
    target: Entity,
    amount: u32,
    is_combat_damage: bool,
}

// Zone change event
#[derive(Event)]
struct ZoneChangeEvent {
    entity: Entity,
    from: ZoneType,
    to: ZoneType,
    cause: ZoneChangeCause,
}
}

Event Handlers

Systems that respond to these events:

#![allow(unused)]
fn main() {
// Handle card drawing
fn handle_draw_event(
    mut events: EventReader<DrawCardEvent>,
    player_hands: Query<(Entity, &ZoneType, &BelongsToPlayer)>,
    player_libraries: Query<(Entity, &ZoneType, &BelongsToPlayer, &ZoneContents)>,
    mut commands: Commands,
    mut zone_events: EventWriter<ZoneChangeEvent>,
) {
    for event in events.iter() {
        // Find player's library and hand
        // Move top N cards from library to hand
        // ...
    }
}

// Handle damage
fn handle_damage_event(
    mut events: EventReader<DamageEvent>,
    mut players: Query<(Entity, &mut Life)>,
    mut creatures: Query<(Entity, &mut Toughness)>,
    mut damage_taken: Query<&mut DamageTaken>,
) {
    for event in events.iter() {
        // Apply damage based on target type
        // ...
    }
}
}

Example Implementations

This section provides complete examples of how complex MTG mechanics are implemented using the ECS architecture.

Creature Combat Example

Here's how the combat system is implemented:

#![allow(unused)]
fn main() {
// Declare attackers
fn declare_attackers_system(
    mut commands: Commands,
    turn_state: Res<TurnState>,
    mut attack_declarations: EventReader<DeclareAttackerEvent>,
    creatures: Query<(Entity, &ControlledBy, &UntappedState), With<CardType::Creature>>,
    active_player: Query<Entity, With<ActivePlayer>>,
    mut phase_events: EventWriter<PhaseChangeEvent>,
) {
    // Validate phase
    if turn_state.phase != Phase::Combat || turn_state.step != Step::DeclareAttackers {
        return;
    }
    
    // Process attack declarations
    for event in attack_declarations.iter() {
        if let Ok((entity, controller, untapped_state)) = creatures.get(event.creature) {
            // Check if creature is controlled by active player and untapped
            if let Ok(active) = active_player.get_single() {
                if controller.0 == active && matches!(untapped_state, UntappedState::Untapped) {
                    // Mark as attacking
                    commands.entity(entity).insert(Attacking { 
                        defending_player: event.target,
                        // Additional attack data
                    });
                    
                    // Tap the creature
                    commands.entity(entity).insert(UntappedState::Tapped);
                }
            }
        }
    }
    
    // When all declarations are done, advance to next step
    phase_events.send(PhaseChangeEvent {
        new_phase: Phase::Combat,
        new_step: Step::DeclareBlockers,
    });
}
}

Card Drawing and Libraries

Implementation of card drawing:

#![allow(unused)]
fn main() {
// Draw card system
fn draw_card_system(
    mut events: EventReader<DrawCardEvent>,
    players: Query<&Player>,
    libraries: Query<(Entity, &ZoneContents, &ZoneType, &BelongsToPlayer)>,
    hands: Query<(Entity, &ZoneType, &BelongsToPlayer)>,
    mut zone_events: EventWriter<ZoneChangeEvent>,
    mut game_events: EventWriter<GameEvent>,
) {
    for event in events.iter() {
        // Find player's library
        let player_library = libraries.iter()
            .find(|(_, _, zone_type, belongs_to)| {
                **zone_type == ZoneType::Library && belongs_to.0 == event.player
            });
        
        if let Some((library_entity, contents, _, _)) = player_library {
            // Check if player can draw enough cards
            if contents.entities.len() < event.amount {
                // Not enough cards - player loses
                game_events.send(GameEvent::PlayerLost {
                    player: event.player,
                    reason: LossReason::EmptyLibrary,
                });
                continue;
            }
            
            // Find player's hand
            let player_hand = hands.iter()
                .find(|(_, zone_type, belongs_to)| {
                    **zone_type == ZoneType::Hand && belongs_to.0 == event.player
                });
            
            if let Some((hand_entity, _, _)) = player_hand {
                // Move cards from library to hand
                for _ in 0..event.amount {
                    if let Some(&card) = contents.entities.last() {
                        zone_events.send(ZoneChangeEvent {
                            entity: card,
                            from: ZoneType::Library,
                            to: ZoneType::Hand,
                            cause: ZoneChangeCause::Draw,
                        });
                    }
                }
            }
        }
    }
}
}

Connecting ECS to MTG Rules

This ECS implementation maps directly to the MTG Comprehensive Rules:

1. Entities: Correspond to objects in the MTG rules (cards, permanents, players)
2. Components: Represent characteristics and states defined in the rules
3. Systems: Implement rules procedures and state transitions
4. Events: Model the discrete game events that trigger rule applications

This mapping ensures that the implementation accurately reflects the official rules while leveraging the performance and flexibility benefits of the ECS architecture.

For more specific implementations, see:

• Turn Structure
• Zones
• Stack
• State-Based Actions
• Combat

Commander Format

This section documents the implementation of the Commander (EDH) format in Rummage, a multiplayer format that emphasizes social gameplay, unique deck construction constraints, and strategic depth.

Note: For a high-level overview of the Commander format rules without implementation details, see the Commander-Specific Rules Reference.

Format Overview

Commander (formerly known as Elder Dragon Highlander or EDH) is a sanctioned Magic: The Gathering format with these defining characteristics:

Documentation Structure

The documentation is organized into the following sections:

• Overview - High-level overview of the Commander format and implementation approach
• Game Mechanics - Core game state and mechanics implementation
  • Game State Management
  • State-Based Actions
  • Random Mechanics (coin flips, dice rolls)
• Player Mechanics - Player-specific rules and interactions
  • Life Total Management
  • Commander Tax
  • Color Identity
• Game Zones - Implementation of game zones, especially the Command Zone
  • Command Zone
  • Zone Transfers
  • Zone-specific Rules
• Turns and Phases - Turn structure and phase management
  • Turn Order
  • Phase Management
  • Multiplayer Considerations
• Stack and Priority - Stack implementation and priority system
  • Priority Passing
  • Stack Resolution
  • Special Timing Rules
• Combat - Combat mechanics including commander damage
  • Combat Phases
  • Commander Damage Tracking
  • Multiplayer Combat
• Special Rules - Format-specific rules and unique mechanics
  • Partner Commanders
  • Commander Death Triggers
  • Commander-specific Abilities
• Core Integration - How Commander extends MTG core rules

Key Mechanics Implementation

Command Zone

The Command Zone serves as the foundation of the format:

#![allow(unused)]
fn main() {
// Command Zone implementation
#[derive(Component)]
struct CommandZone {
    owner: Entity,
    contents: Vec<Entity>,
}

// Commander component
#[derive(Component)]
struct Commander {
    owner: Entity,
    cast_count: u32,
}
}

Key implementations:

• Commanders start in the Command Zone
• Zone transfer options when commanders change zones
• Commander Tax calculation (2 additional mana per previous cast)

Commander Damage Tracking

#![allow(unused)]
fn main() {
// Tracking damage from each commander
#[derive(Component)]
struct CommanderDamageTracker {
    // Maps commander entities to damage received
    damage_taken: HashMap<Entity, u32>,
}

// System that checks for commander damage loss condition
fn check_commander_damage_loss(
    tracker: Query<(Entity, &CommanderDamageTracker, &Player)>,
    mut game_events: EventWriter<GameEvent>,
) {
    for (entity, tracker, player) in &tracker {
        for (_, damage) in tracker.damage_taken.iter() {
            if *damage >= 21 {
                game_events.send(GameEvent::PlayerLost {
                    player: entity,
                    reason: LossReason::CommanderDamage,
                });
                break;
            }
        }
    }
}
}

Key Commander Rules

The following key Commander rules are implemented in our engine:

Technical Implementation

The Commander format is implemented as a Bevy plugin that extends the core MTG rules:

#![allow(unused)]
fn main() {
pub struct CommanderPlugin;

impl Plugin for CommanderPlugin {
    fn build(&self, app: &mut App) {
        app
            // Commander components
            .register_type::<Commander>()
            .register_type::<CommanderDamage>()
            .register_type::<ColorIdentity>()
            
            // Commander resources
            .init_resource::<CommanderConfig>()
            
            // Commander systems
            .add_systems(Startup, commander_game_setup)
            .add_systems(
                PreUpdate,
                (check_commander_zone_transfers, validate_color_identity)
            )
            .add_systems(
                Update,
                (track_commander_damage, apply_commander_tax)
            );
    }
}
}

Testing Strategy

Commander testing focuses on these key areas:

1. Rule Compliance: Verifying all Commander-specific rules
2. Integration Testing: Testing interaction with core MTG systems
3. Multiplayer Scenarios: Validating complex multiplayer situations
4. Edge Cases: Partner commanders, commander ninjutsu, and other special mechanics

Each section includes detailed test cases to validate the correct implementation of Commander rules. Our testing approach ensures:

1. Full coverage of Commander-specific rules
2. Edge case handling for unique interactions
3. Performance validation for multiplayer scenarios
4. Verification of correct rule application in complex board states

For detailed testing approaches, see the Commander Testing Guide.

Implementation Status

For more information on the official Commander rules, refer to the Commander Format Rules.

Commander Overview

This section provides a high-level overview of the Commander format implementation in our game engine.

Contents

• Format Rules - Core rules specific to the Commander format
• Architecture - Overview of the implementation architecture
• Implementation Approach - General approach to implementing the Commander format

Format Summary

The Commander format is a multiplayer variant of Magic: The Gathering with special rules including:

• Each player begins the game with a designated legendary creature as their "commander"
• Players start with 40 life
• A player can cast their commander from the command zone for its mana cost, plus an additional 2 mana for each previous time it's been cast
• If a commander would be put into a library, hand, graveyard or exile, its owner may choose to move it to the command zone
• A player who has been dealt 21 or more combat damage by the same commander loses the game

Implementation Principles

Our implementation of the Commander format follows these key principles:

1. Rule Accuracy - Faithful implementation of the official Commander rules
2. Performance - Optimized for multiplayer games with complex board states
3. Extensibility - Designed to easily incorporate new Commander-specific cards and mechanics
4. Testability - Comprehensive test suite for validating format-specific rules

See the Implementation Approach document for more detailed information on how these principles are applied in our codebase.

Related Sections

• Game Mechanics - For detailed mechanics implementation
• Combat - For Commander damage tracking and combat interactions
• Game Zones - For Command Zone implementation details

Commander Format History

Commander (formerly known as Elder Dragon Highlander or EDH) has an interesting history that evolved from a casual player-created format to one of Magic: The Gathering's most popular formats today.

Origins

The Commander format was created in the late 1990s by judges in Alaska who were looking for a new way to play between tournament rounds. The format was originally called "Elder Dragon Highlander" (EDH) because:

• Players were required to use one of the five Elder Dragons from Legends as their general (later called commander)
• The "Highlander" part referenced the 1986 film and its tagline "There can be only one," signifying the singleton nature of the format

Evolution of the Format

Rules Committee

The Commander format is officially governed by the Commander Rules Committee (RC), an independent group that:

• Maintains the format's rules and banned list
• Makes decisions about format changes
• Promotes the philosophy of Commander as a social, multiplayer format

The Rules Committee maintains that Commander should remain primarily a social format that emphasizes fun, memorable gameplay over competition.

Implementation in Rummage

In Rummage, we've faithfully implemented the Commander format according to the official rules while maintaining the flexibility to adapt to future changes. Our implementation:

• Follows the current Commander rules
• Includes historical context in design decisions
• Allows for easy adaptation to rule changes

References

For more information on the official Commander rules and history:

• Official Commander Website
• Commander Rules Committee
• Magic: The Gathering Official Commander Page

Key Principles of Commander

The Commander format is built upon core design principles that guide both the rules and the social contract of the format. These principles inform our implementation in Rummage.

Social Focus

Commander was designed as a multiplayer, social format where:

1. Fun and memorable gameplay takes precedence over competitive optimization
2. Politics and table talk are encouraged
3. The journey of the game is as important as the outcome
4. Players are encouraged to build decks that express their identity and creativity

Format Pillars

Variance and Uniqueness

The singleton requirement (only one copy of each card except basic lands) ensures:

• Every game plays differently
• Decks feel unique and personalized
• Players must be adaptable to changing game states
• Card evaluation differs from other formats

Commander Identity

The commander serves as:

• The centerpiece of the deck's strategy
• A constant presence throughout the game
• A representation of the player's identity
• A build-around card that shapes deckbuilding decisions

Multiplayer Dynamics

Commander embraces multiplayer game design through:

• Balanced starting life totals (40 life)
• Political elements like deal-making and temporary alliances
• Mechanics that encourage table-wide interactions
• Rules that prevent early eliminations when possible

Design Philosophy

The Commander Rules Committee articulates the following design philosophy:

Commander is designed to promote social games of magic. It suits players who want to:

• Cultivate a casual atmosphere where everyone can have fun, not just the winner
• Build personalized decks that showcase interesting cards and strategies
• Create game states full of twists and turns that lead to epic plays and memorable moments

Implementation in Rummage

Our implementation of Commander in Rummage emphasizes:

1. Faithful Rules Implementation: Accurate implementation of the official rules
2. Social Features: Support for politics, deals, and multiplayer interactions
3. Player Expression: Flexible deck building and commander options
4. Game Variance: Random elements and complexity that lead to unique game states
5. Accessibility: Clear visualizations of complex board states and commander-specific rules

Rules vs. Social Contract

We recognize that Commander has both written rules and an unwritten social contract. While we can fully implement the rules, the social contract is up to players. We provide:

• Tools for communication between players
• Flexibility in game settings
• Support for house rules when possible
• Documentation that explains both rules and social expectations

Commander Format Rules

Overview

Commander (formerly known as Elder Dragon Highlander or EDH) is a multiplayer variant of Magic: The Gathering with special rules defined in section 903 of the Magic: The Gathering Comprehensive Rules.

Core Rules

1. Deck Construction (rule 903.5)

   • 100-card singleton format (only one copy of each card except for basic lands)
   • Deck can only include cards that match the color identity of the commander
   • Color identity includes all colored mana symbols in the card's cost, rules text, and color indicator

2. Commander Card (rule 903.3)

   • Each player designates a legendary creature as their "commander"
   • The commander is placed in the command zone at the start of the game
   • Partner commanders and Background mechanics allow for special exceptions

3. Life Total (rule 903.7)

   • Players start with 40 life (instead of the standard 20)

4. Command Zone Mechanics (rules 903.8, 903.9)

   • Commanders start in the command zone
   • Commanders can be cast from the command zone for their mana cost, plus an additional {2} for each previous time they've been cast from the command zone ("commander tax")
   • If a commander would be put into a library, hand, graveyard, or exile, its owner may choose to move it to the command zone instead

5. Commander Damage (rule 903.10)

   • A player who has been dealt 21 or more combat damage by the same commander loses the game

6. Banned Cards (rule 903.11)

   • The Commander format has its own banned list maintained by the Commander Rules Committee

Additional Rules

1. Multiplayer Rules

   • Standard multiplayer rules apply (first player doesn't draw, etc.)
   • Free-for-all, attack-anyone format unless playing with teams

2. Color Identity

   • A card's color identity includes all mana symbols in its cost and rules text
   • Cards in a player's deck must only contain mana symbols that appear in their commander's color identity
   • Basic land types implicitly have the corresponding mana symbol in their identity

3. Replacement Commander

   • In casual play, if a player's commander would be put into a library, hand, graveyard or exile from anywhere, that player may put it into the command zone instead

These rules create a unique gameplay experience that emphasizes multiplayer interaction, powerful cards, and distinctive deck construction constraints.

Implementation Approach

Core Principles

Our implementation of the Commander format follows these key principles:

1. Rules Accuracy - Faithfully implement the official Magic: The Gathering Comprehensive Rules for Commander (section 903)
2. Modularity - Clear separation of concerns between different aspects of the game engine
3. Testability - Comprehensive testing for complex rule interactions
4. Performance - Optimized for multiplayer games with up to 13 players
5. Extensibility - Easily accommodate new Commander variants and house rules

Technology Stack

The implementation uses the following technologies:

1. Bevy ECS - For game state management and systems organization
2. Rust - For type safety and performance
3. Event-driven architecture - For game actions and triggers
4. Automated testing - For rules validation and edge cases

Key Implementation Techniques

1. Component-Based Design

   #![allow(unused)]
   fn main() {
   // Components for different aspects of game entities
   #[derive(Component)]
   pub struct Commander {
       pub cast_count: u32,
   }
   
   #[derive(Component)]
   pub struct CommanderDamage {
       // Maps commander entity ID to damage received
       pub damage_received: HashMap<Entity, u32>,
   }
   }

2. Resource-Based Game State

   #![allow(unused)]
   fn main() {
   #[derive(Resource)]
   pub struct CommanderGameState {
       pub active_player_index: usize,
       pub player_order: Vec<Entity>,
       pub current_phase: Phase,
       // More fields
   }
   }

3. Event-Driven Actions

   #![allow(unused)]
   fn main() {
   #[derive(Event)]
   pub struct CommanderCastEvent {
       pub commander: Entity,
       pub player: Entity,
       pub from_zone: Zone,
   }
   }

4. Systems for Game Logic

   #![allow(unused)]
   fn main() {
   fn commander_damage_system(
       mut commands: Commands,
       game_state: Res<CommanderGameState>,
       mut damage_events: EventReader<CommanderDamageEvent>,
       mut players: Query<(Entity, &mut CommanderDamage)>,
   ) {
       // Logic implementation
   }
   }

Development Approach

1. Incremental Implementation

   • Start with core game state management
   • Layer in Commander-specific rules
   • Add multiplayer functionality
   • Implement special cases and edge conditions

2. Testing Strategy

   • Unit tests for individual components
   • Integration tests for system interactions
   • Scenario-based tests for complex rule interactions
   • Performance tests for multiplayer scenarios

3. Documentation

   • Comprehensive documentation of implementation details
   • Cross-referencing with official rules
   • Examples of complex interactions

This structured approach ensures a robust implementation of the Commander format that accurately reflects the official rules while maintaining performance and extensibility.

Architecture Overview

System Architecture

The Commander rules engine is organized into several interconnected modules that work together to provide a complete implementation of the Commander format:

1. Game State Management

   • Core state tracking and game flow coordination
   • Central resource for game metadata and state
   • Integration point for all other systems

2. Player Management

   • Player data structures and tracking
   • Life total management (starting at 40)
   • Commander damage tracking

3. Command Zone Management

   • Special zone for Commander cards
   • Commander casting and tax implementation
   • Zone transition rules

4. Turn Structure & Phases

   • Complete turn sequence implementation
   • Priority passing in multiplayer context
   • Phase-based effects and triggers

5. Combat System

   • Multiplayer combat implementation
   • Commander damage tracking
   • Attack declaration and blocking in multiplayer

6. Priority & Stack

   • Priority passing algorithms for multiplayer
   • Stack implementation for spells and abilities
   • Resolution mechanics in complex scenarios

7. State-Based Actions

   • Game state checks including commander damage threshold (21)
   • Format-specific state checks
   • Automatic game actions

8. Special Commander Rules

   • Color identity validation
   • Commander zone movement replacement effects
   • Partner and Background mechanics

9. Multiplayer Politics

   • Voting mechanics
   • Deal-making systems
   • Multiplayer-specific card effects

Integration with Bevy ECS

The Commander implementation leverages Bevy ECS (Entity Component System) for game state management:

#![allow(unused)]
fn main() {
// Game state as a Bevy resource
#[derive(Resource)]
pub struct CommanderGameState {
    // Game state fields
}

// Player as an entity with components
#[derive(Component)]
pub struct CommanderPlayer {
    // Player data
}

// Systems for game logic
fn process_commander_damage(
    mut game_state: ResMut<CommanderGameState>,
    query: Query<(&CommanderPlayer, &CommanderDamage)>,
) {
    // Implementation
}
}

The architecture allows for clean separation of concerns while maintaining the complex relationships between different aspects of the Commander format.

Game Mechanics

This section covers the core game mechanics specific to the Commander format implementation.

Contents

• Game State - Core state tracking and management
• State-Based Actions - Commander-specific state checks and automatic game actions
• Triggered Abilities - Commander-specific triggered abilities and effects
• Random Elements - Testing random elements like coin flips and dice rolls
• Testing Guide - Special considerations for testing Commander mechanics

The game mechanics section defines how the Commander format's unique rules are implemented and enforced within our game engine, including:

• Commander-specific state tracking
• Unique state-based actions like commander damage checks
• Special triggered abilities for command zone interactions
• Format-specific mechanics like Lieutenant and Partner triggers
• Handling multiple player elimination and game completion
• Randomized mechanics like coin flips and dice rolls

These mechanics build on the foundational Magic: The Gathering rules while incorporating the unique aspects of the Commander format. The implementation is designed to be both accurate to the official rules and performant for multiplayer gameplay.

Game Engine Testing Guide

Overview

This guide outlines the comprehensive testing approach for the Rummage Magic: The Gathering Commander game engine. Testing a complex game engine requires multiple layers of validation to ensure rules are correctly implemented and interactions work as expected.

Testing Philosophies

The Rummage testing strategy follows these core philosophies:

1. Rules-First Testing: Test cases are derived directly from the MTG Comprehensive Rules
2. Isolation and Integration: Test components in isolation before testing their interactions
3. Edge Case Coverage: Explicitly test corner cases and unusual card interactions
4. Performance Validation: Ensure the engine performs well under various game conditions
5. Reproducibility: All tests should be deterministic and repeatable
6. Visual Consistency: Ensure consistent rendering across platforms and game states

Testing Layers

The game engine testing is structured in layers:

1. Unit Tests

Unit tests validate individual components in isolation. Each module should have comprehensive unit tests covering:

• Basic functionality
• Edge cases
• Error handling
• Public interface contracts

Example for the stack system:

#![allow(unused)]
fn main() {
#[test]
fn test_stack_push_and_resolve() {
    let mut app = App::new();
    // Setup minimal test environment
    app.add_plugins(MinimalPlugins)
       .add_plugin(StackPlugin);
    
    // Add a spell to the stack
    let spell_entity = app.world.spawn_empty().id();
    app.world.send_event(StackPushEvent {
        entity: spell_entity,
        source: None,
    });
    
    // Run systems
    app.update();
    
    // Verify stack state
    let stack = app.world.resource::<Stack>();
    assert_eq!(stack.items.len(), 1);
    
    // Resolve the top item
    app.world.send_event(StackResolveTopEvent);
    app.update();
    
    // Verify stack is empty
    let stack = app.world.resource::<Stack>();
    assert_eq!(stack.items.len(), 0);
}
}

2. Integration Tests

Integration tests verify the interaction between multiple components. Key integration scenarios include:

• Turn structure and phase progression
• Combat resolution
• Stack interaction with permanents
• Zone transitions

Example integration test:

#![allow(unused)]
fn main() {
#[test]
fn test_spell_cast_and_resolve_integration() {
    let mut app = App::new();
    // Setup more complete environment
    app.add_plugins(GameEngineTestPlugins)
       .add_systems(Startup, setup_test_game);
    
    // Create test player and card
    let (player, card) = setup_test_player_with_card(&mut app);
    
    // Cast the spell
    app.world.send_event(CastSpellEvent {
        player,
        card,
        targets: Vec::new(),
        mode: CastMode::Normal,
    });
    
    // Run systems to process the cast
    app.update();
    
    // Verify card moved to stack
    let stack = app.world.resource::<Stack>();
    assert!(stack.contains(card));
    
    // Resolve the stack
    resolve_stack_completely(&mut app);
    
    // Verify expected outcome based on card type
    let card_type = app.world.get::<CardType>(card).unwrap();
    match *card_type {
        CardType::Creature => {
            // Verify creature entered battlefield
            let battlefield = app.world.resource::<Battlefield>();
            assert!(battlefield.contains(card));
        },
        CardType::Sorcery => {
            // Verify sorcery went to graveyard
            let graveyard = get_player_graveyard(&app, player);
            assert!(graveyard.contains(card));
        },
        // Handle other card types
        _ => {}
    }
}
}

3. End-to-End Tests

End-to-end tests simulate complete game scenarios to validate the engine as a whole:

#![allow(unused)]
fn main() {
#[test]
fn test_complete_game_scenario() {
    let mut app = App::new();
    // Setup full game environment
    app.add_plugins(FullGameTestPlugins)
       .add_systems(Startup, setup_full_test_game);
    
    // Load predefined scenario
    let scenario = TestScenario::load("scenarios/two_player_creature_combat.json");
    scenario.apply_to_app(&mut app);
    
    // Run a fixed number of turns
    run_turns(&mut app, 3);
    
    // Verify expected game state
    let game_state = app.world.resource::<GameState>();
    assert_eq!(game_state.active_player_index, 1);
    
    // Verify player life totals
    let players = app.world.query::<&Player>().iter(&app.world).collect::<Vec<_>>();
    assert_eq!(players[0].life_total, 35);
    assert_eq!(players[1].life_total, 38);
    
    // Verify battlefield state
    let battlefield = app.world.resource::<Battlefield>();
    assert_eq!(battlefield.creatures_for_player(players[0].entity).count(), 2);
    assert_eq!(battlefield.creatures_for_player(players[1].entity).count(), 1);
}
}

4. Visual Differential Testing

Visual differential testing ensures consistent rendering across platforms and updates:

#![allow(unused)]
fn main() {
#[test]
fn test_card_rendering_consistency() {
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_plugin(VisualTestingPlugin)
       .add_systems(Startup, setup_card_rendering_test);
    
    // Configure test environment
    let card_states = [
        "in_hand", 
        "on_battlefield", 
        "tapped", 
        "with_counters"
    ];
    
    for state in &card_states {
        // Configure card state
        setup_card_state(&mut app, state);
        app.update();
        
        // Capture rendering
        if let Some(screenshot) = take_screenshot(&app) {
            // Compare with reference
            match load_reference_image(&format!("card_{}.png", state)) {
                Ok(reference) => {
                    let result = compare_images(&screenshot, &reference);
                    assert!(
                        result.similarity_score > 0.99, 
                        "Card rendering for state '{}' differs from reference", 
                        state
                    );
                },
                Err(_) => {
                    // Generate reference if not exists
                    let _ = save_reference_image(screenshot, &format!("card_{}.png", state));
                }
            }
        }
    }
}
}

Test Data Management

Card Test Database

A specialized test card database simplifies testing of specific interactions:

#![allow(unused)]
fn main() {
// Access test cards by specific properties
let board_wipe = test_cards::get_card("board_wipe");
let counter_spell = test_cards::get_card("counter_spell");
let indestructible_creature = test_cards::get_card("indestructible_creature");

// Test interaction
test_interaction(board_wipe, indestructible_creature);
}

Scenario Files

Predefined test scenarios enable reproducible complex game states:

{
  "players": [
    {
      "name": "Player 1",
      "life": 40,
      "battlefield": ["test_cards/serra_angel", "test_cards/sol_ring"],
      "hand": ["test_cards/counterspell", "test_cards/lightning_bolt"],
      "graveyard": ["test_cards/llanowar_elves"]
    },
    {
      "name": "Player 2",
      "life": 36,
      "battlefield": ["test_cards/goblin_guide", "test_cards/birds_of_paradise"],
      "hand": ["test_cards/wrath_of_god"],
      "graveyard": []
    }
  ],
  "turn": {
    "active_player": 0,
    "phase": "main1",
    "priority_player": 0
  }
}

Testing Particular Systems

Mana System Testing

The mana system requires specific testing for:

1. Mana Production: Test ability to produce mana from various sources
2. Mana Payment: Test payment for spells and abilities
3. Mana Restrictions: Test "spend only on X" restrictions
4. Color Identity: Test commander color identity rules

#![allow(unused)]
fn main() {
#[test]
fn test_mana_restrictions() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_plugin(ManaPlugin);
    
    // Create a player with a mana pool
    let player = setup_test_player(&mut app);
    
    // Add mana with "spend this mana only on creature spells" restriction
    add_restricted_mana(&mut app, player, ManaColor::Green, 3, ManaRestriction::CreatureSpells);
    
    // Test allowed payment
    let creature_card = spawn_test_card(&mut app, "Grizzly Bears");
    let result = try_pay_mana_cost(&mut app, player, creature_card);
    assert!(result.is_success);
    
    // Test restricted payment
    let noncreature_card = spawn_test_card(&mut app, "Giant Growth");
    let result = try_pay_mana_cost(&mut app, player, noncreature_card);
    assert!(result.is_failure);
    assert_eq!(result.failure_reason, ManaPaymentFailure::RestrictionViolation);
}
}

Combat System Testing

Combat testing should validate:

1. Attack Declaration: Rules about who can attack
2. Blocker Declaration: Valid blocking assignments
3. Combat Damage: Correct damage assignment and processing
4. Combat Effects: Triggers that happen during combat

#![allow(unused)]
fn main() {
#[test]
fn test_combat_damage_assignment() {
    let mut app = App::new();
    app.add_plugins(GameEngineTestPlugins);
    
    // Setup attacker with 4/4 stats
    let attacker = spawn_test_creature(&mut app, 4, 4);
    
    // Setup two blockers: 2/2 and 1/1
    let blocker1 = spawn_test_creature(&mut app, 2, 2);
    let blocker2 = spawn_test_creature(&mut app, 1, 1);
    
    // Declare attack
    declare_attacker(&mut app, attacker);
    
    // Declare blockers
    declare_blockers(&mut app, vec![blocker1, blocker2], attacker);
    
    // Assign damage: 2 to first blocker, 2 to second blocker
    assign_combat_damage(&mut app, attacker, vec![(blocker1, 2), (blocker2, 2)]);
    
    // Process damage
    process_combat_damage(&mut app);
    
    // Verify results
    assert!(is_creature_dead(&app, blocker1));
    assert!(is_creature_dead(&app, blocker2));
    assert!(!is_creature_dead(&app, attacker));
}
}

Stack and Priority Testing

Testing stack interactions requires:

1. Proper Sequencing: Items resolve in LIFO order
2. Priority Passing: Correct priority assignment during resolution
3. Interruption: Ability to respond to items on the stack
4. Special Actions: Actions that don't use the stack

#![allow(unused)]
fn main() {
#[test]
fn test_stack_priority_and_responses() {
    let mut app = App::new();
    app.add_plugins(GameEngineTestPlugins);
    
    // Setup players
    let player1 = setup_test_player(&mut app);
    let player2 = setup_test_player(&mut app);
    
    // Setup cards
    let lightning_bolt = spawn_test_card(&mut app, "Lightning Bolt");
    let counterspell = spawn_test_card(&mut app, "Counterspell");
    
    // Give cards to players
    give_card_to_player(&mut app, lightning_bolt, player1);
    give_card_to_player(&mut app, counterspell, player2);
    
    // Player 1 casts Lightning Bolt
    cast_spell(&mut app, player1, lightning_bolt, Some(player2));
    
    // Verify Lightning Bolt is on the stack
    let stack = app.world.resource::<Stack>();
    assert_eq!(stack.items.len(), 1);
    
    // Player 2 responds with Counterspell
    cast_spell(&mut app, player2, counterspell, Some(lightning_bolt));
    
    // Verify both spells are on the stack
    let stack = app.world.resource::<Stack>();
    assert_eq!(stack.items.len(), 2);
    assert_eq!(stack.items[0].card, counterspell);
    assert_eq!(stack.items[1].card, lightning_bolt);
    
    // Resolve stack
    resolve_stack_completely(&mut app);
    
    // Verify both cards went to graveyard and Lightning Bolt didn't deal damage
    assert!(is_card_in_graveyard(&app, counterspell, player2));
    assert!(is_card_in_graveyard(&app, lightning_bolt, player1));
    
    let player2_resource = app.world.get::<Player>(player2).unwrap();
    assert_eq!(player2_resource.life_total, 40); // Unchanged
}
}

Testing Best Practices

Arrange-Act-Assert Pattern

Follow the Arrange-Act-Assert pattern in test implementation:

#![allow(unused)]
fn main() {
#[test]
fn test_some_functionality() {
    // ARRANGE: Set up the test environment
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_plugin(SystemUnderTest);
    
    let test_entity = setup_test_entity(&mut app);
    
    // ACT: Perform the action being tested
    perform_action(&mut app, test_entity);
    app.update(); // Run systems
    
    // ASSERT: Verify expected outcomes
    let result = get_result(&app, test_entity);
    assert_eq!(result, expected_value);
}
}

Use Test Fixtures

Create reusable test fixtures to simplify test implementation:

#![allow(unused)]
fn main() {
// Fixture for tests involving combat
fn setup_combat_fixture(app: &mut App) -> CombatFixture {
    app.add_plugins(MinimalPlugins)
       .add_plugin(CombatPlugin);
       
    let player1 = app.world.spawn((Player { life_total: 40, ..Default::default() })).id();
    let player2 = app.world.spawn((Player { life_total: 40, ..Default::default() })).id();
    
    let attacker = app.world.spawn((
        Creature { power: 3, toughness: 3, ..Default::default() },
        Permanent { controller: player1, ..Default::default() },
    )).id();
    
    let blocker = app.world.spawn((
        Creature { power: 2, toughness: 2, ..Default::default() },
        Permanent { controller: player2, ..Default::default() },
    )).id();
    
    CombatFixture {
        player1,
        player2,
        attacker,
        blocker,
    }
}
}

Focused Test Cases

Keep test cases focused on a single behavior or requirement:

#![allow(unused)]
fn main() {
// GOOD: Focused test
#[test]
fn creatures_with_deathtouch_destroy_blockers() {
    // Test setup
    let creature_with_deathtouch = setup_deathtouch_creature();
    let normal_creature = setup_normal_creature();
    
    // Combat interaction
    simulate_combat(creature_with_deathtouch, normal_creature);
    
    // Verification
    assert!(normal_creature.is_destroyed());
}

// BAD: Unfocused test
#[test]
fn test_deathtouch_and_trample_and_first_strike() {
    // Too many interactions being tested at once
    // Makes it hard to understand test failures
}
}

Property-Based Testing

Use property-based testing for rules that should hold across many inputs:

#![allow(unused)]
fn main() {
#[test]
fn test_mana_payment_properties() {
    proptest!(|(cost: ManaCost, mana_pool: ManaPool)| {
        // Property: If payment succeeds, the mana pool should decrease by exactly the cost
        let initial_total = mana_pool.total_mana();
        let result = pay_mana_cost(cost, &mut mana_pool.clone());
        
        if result.is_success {
            let new_total = mana_pool.total_mana();
            let used_mana = initial_total - new_total;
            
            // The mana used should equal the cost
            prop_assert_eq!(used_mana, cost.total_mana());
        }
    });
}
}

Test Debugging Tools

Logging in Tests

Use descriptive logging to help debug test failures:

#![allow(unused)]
fn main() {
#[test]
fn test_with_detailed_logging() {
    // Set up the test
    info!("Setting up test with player 1 having 3 creatures and player 2 having 2 enchantments");
    
    // Configure logging level for test
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_plugin(LogPlugin {
            level: Level::DEBUG,
            filter: "test=debug,game_engine=debug".to_string(),
       });
    
    // Detailed action description
    debug!("Player 1 casting board wipe spell");
    
    // Log outcome for debugging
    info!("Expected: All creatures destroyed, enchantments remain. Got: {} creatures, {} enchantments",
          remaining_creatures, remaining_enchantments);
}
}

State Snapshots

Create snapshots of game state for easier debugging:

#![allow(unused)]
fn main() {
#[test]
fn test_complex_interaction() {
    let mut app = App::new();
    // Setup test
    
    // Take snapshot before action
    let before_snapshot = take_game_state_snapshot(&app);
    save_snapshot("before_action.json", &before_snapshot);
    
    // Perform action
    perform_complex_action(&mut app);
    
    // Take snapshot after action
    let after_snapshot = take_game_state_snapshot(&app);
    save_snapshot("after_action.json", &after_snapshot);
    
    // Verify expected changes
    verify_state_changes(&before_snapshot, &after_snapshot);
}
}

Performance Testing

Include performance testing as part of your test suite:

#![allow(unused)]
fn main() {
#[test]
fn benchmark_large_board_state() {
    let mut app = App::new();
    app.add_plugins(GameEngineTestPlugins);
    
    // Create a large board state
    setup_large_board_state(&mut app, 100); // 100 permanents per player
    
    // Measure time for operations
    let start = std::time::Instant::now();
    process_turn_cycle(&mut app);
    let duration = start.elapsed();
    
    // Log performance results
    info!("Processing turn with large board took: {:?}", duration);
    
    // Assert performance requirements
    assert!(duration < std::time::Duration::from_millis(100),
            "Turn processing too slow: {:?}", duration);
}
}

Continuous Integration

Ensure your tests run in CI:

# .github/workflows/tests.yml
name: Game Engine Tests

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Rust
        uses: actions-rs/toolchain@v1
        with:
          profile: minimal
          toolchain: stable
      
      - name: Run unit tests
        run: cargo test --lib
        
      - name: Run integration tests
        run: cargo test --test integration
        
      - name: Run visual tests
        run: cargo test --test visual
        
      - name: Run performance tests
        run: cargo test --test performance

Common Testing Patterns

Singleton Resource Validation

#![allow(unused)]
fn main() {
#[test]
fn test_resource_update() {
    let mut app = App::new();
    app.add_plugins(MinimalPlugins);
    
    // Add initial resource
    app.insert_resource(GameState {
        turn_count: 0,
        active_player: 0,
    });
    
    // Add system that increments turn count
    app.add_systems(Update, increment_turn_system);
    
    // Run system
    app.update();
    
    // Verify resource was updated
    let game_state = app.world.resource::<GameState>();
    assert_eq!(game_state.turn_count, 1);
}
}

Event Testing

#![allow(unused)]
fn main() {
#[test]
fn test_event_handling() {
    let mut app = App::new();
    app.add_plugins(MinimalPlugins);
    
    // Add event and system
    app.add_event::<CardDrawEvent>();
    app.add_systems(Update, handle_card_draw);
    
    // Send test event
    app.world.resource_mut::<Events<CardDrawEvent>>().send(CardDrawEvent {
        player: Entity::from_raw(1),
        count: 3,
    });
    
    // Run system
    app.update();
    
    // Verify event was handled (check side effects)
    // ...
}
}

Component Addition/Removal

#![allow(unused)]
fn main() {
#[test]
fn test_component_addition() {
    let mut app = App::new();
    app.add_plugins(MinimalPlugins);
    
    // System that adds components
    app.add_systems(Update, add_damage_component_system);
    
    // Create test entity
    let entity = app.world.spawn(Creature {
        power: 2,
        toughness: 2,
    }).id();
    
    // Trigger damage
    app.world.resource_mut::<Events<DamageEvent>>().send(DamageEvent {
        target: entity,
        amount: 1,
    });
    
    // Run system
    app.update();
    
    // Verify component was added
    assert!(app.world.get::<Damaged>(entity).is_some());
    assert_eq!(app.world.get::<Damaged>(entity).unwrap().amount, 1);
}
}

Conclusion

A comprehensive testing strategy is essential for the Rummage MTG Commander game engine. By combining unit tests, integration tests, end-to-end tests, and visual tests, we can ensure that the engine correctly implements the MTG rules and provides a consistent player experience.

Remember, an untested game engine is a source of bugs and inconsistencies. Invest time in creating a robust test suite, and it will pay dividends in reduced debugging time and improved game quality.

State-Based Actions

Overview

State-Based Actions (SBAs) are checks that the game automatically performs regularly, ensuring game rules are enforced without requiring player actions. These checks occur whenever a player would receive priority and before any player actually receives priority.

Core Functionality

In Commander, state-based actions handle crucial game state validations:

• Player loss conditions (life total at or below 0, drawing from an empty library, poison counters)
• Commander damage tracking (21+ damage from a single commander)
• Creature destruction (zero or negative toughness, lethal damage)
• Planeswalker loyalty management
• Aura and Equipment attachment rules
• Legendary permanents uniqueness rule
• Token existence rules
• Counters on permanents (especially +1/+1 and -1/-1 counter interaction)

Implementation

The state-based actions system is implemented as a collection of systems that run between steps and phases:

#![allow(unused)]
fn main() {
#[derive(Resource)]
pub struct StateBasedActionSystem {
    // Configuration for SBA processing
    pub enabled: bool,
    pub last_check_time: Duration,
    pub check_frequency: Duration,
    
    // Tracking for specific SBAs
    pub pending_legendary_checks: Vec<Entity>,
    pub pending_destruction: Vec<Entity>,
    pub pending_life_checks: Vec<Entity>,
}

// Systems that implement specific checks
pub fn check_player_loss_conditions(/* ... */);
pub fn check_creature_destruction(/* ... */);
pub fn check_attachment_validity(/* ... */);
pub fn check_legendary_rule(/* ... */);
pub fn check_token_existence(/* ... */);
pub fn check_counter_interactions(/* ... */);
}

Special Commander Rules

Commander format introduces specific state-based actions:

• Commander Damage: When a player has been dealt 21 or more combat damage by the same commander, they lose the game
• Commander Zone Transitions: Commanders can be moved to the command zone instead of other zones
• Color Identity: Cards that would be added to a library, hand, battlefield or graveyard are checked against the commander's color identity

Multiplayer Considerations

In multiplayer Commander:

• State-based actions are checked simultaneously for all players and permanents
• Player elimination is handled through SBAs, with appropriate triggers firing
• When a player leaves the game, all cards they own leave the game (with special rules for controlled permanents)

Optimization

The SBA system is optimized to:

• Only check relevant game objects (using spatial partitioning where appropriate)
• Use efficient data structures to track pending actions
• Batch similar checks where possible
• Cache results when appropriate

Commander-Specific Triggered Abilities

This document details the implementation of triggered abilities that are specific to or modified by the Commander format.

Overview

Triggered abilities in Commander generally follow the same rules as in standard Magic: The Gathering. However, there are several Commander-specific triggers and interactions that require special implementation:

1. Triggers that reference the command zone
2. Commander-specific card triggers
3. Multiplayer-specific triggers
4. Commander death and zone change triggers

Command Zone Triggers

Triggered abilities that interact with the command zone require special handling:

#![allow(unused)]
fn main() {
/// Component for abilities that trigger when a commander enters or leaves the command zone
#[derive(Component)]
pub struct CommandZoneTrigger {
    /// The event that triggers this ability
    pub trigger_event: CommandZoneEvent,
    /// The effect to apply
    pub effect: Box<dyn CommandZoneEffect>,
}

/// Events related to the command zone
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CommandZoneEvent {
    /// Triggers when a commander enters the command zone
    OnEnter,
    /// Triggers when a commander leaves the command zone
    OnLeave,
    /// Triggers when a commander is cast from the command zone
    OnCast,
}

/// System that handles command zone triggers
pub fn handle_command_zone_triggers(
    mut commands: Commands,
    mut zone_transition_events: EventReader<ZoneTransitionEvent>,
    mut cast_events: EventReader<CastFromCommandZoneEvent>,
    command_zone_triggers: Query<(Entity, &CommandZoneTrigger, &Controller)>,
    commanders: Query<(Entity, &Commander, &Owner)>,
) {
    // Handle zone transitions
    for event in zone_transition_events.read() {
        // Check if this is a commander
        if let Ok((commander_entity, _, owner)) = commanders.get(event.entity) {
            // Handle entering command zone
            if event.to == Zone::Command {
                trigger_command_zone_abilities(
                    CommandZoneEvent::OnEnter,
                    commander_entity,
                    owner.0,
                    &command_zone_triggers,
                    &mut commands,
                );
            }
            
            // Handle leaving command zone
            if event.from == Zone::Command {
                trigger_command_zone_abilities(
                    CommandZoneEvent::OnLeave,
                    commander_entity,
                    owner.0,
                    &command_zone_triggers,
                    &mut commands,
                );
            }
        }
    }
    
    // Handle cast events
    for event in cast_events.read() {
        trigger_command_zone_abilities(
            CommandZoneEvent::OnCast,
            event.commander,
            event.controller,
            &command_zone_triggers,
            &mut commands,
        );
    }
}

fn trigger_command_zone_abilities(
    event: CommandZoneEvent,
    commander: Entity,
    controller: Entity,
    triggers: &Query<(Entity, &CommandZoneTrigger, &Controller)>,
    commands: &mut Commands,
) {
    // Find all triggers that match this event
    for (trigger_entity, trigger, trigger_controller) in triggers.iter() {
        // Only trigger if the ability belongs to the controller of the commander
        if trigger_controller.0 == controller && trigger.trigger_event == event {
            // Create and resolve the triggered ability
            let ability_id = commands.spawn_empty().id();
            
            // Set up ability context
            let mut ctx = AbilityContext {
                ability: ability_id,
                source: trigger_entity,
                controller,
                targets: vec![commander],
                additional_data: HashMap::new(),
            };
            
            // Apply the effect
            trigger.effect.resolve(commands.world_mut(), &mut ctx);
        }
    }
}
}

Commander Death Triggers

The Commander format has specific rules about commanders changing zones and death triggers:

#![allow(unused)]
fn main() {
/// System that handles commander death triggers
pub fn handle_commander_death_triggers(
    mut death_events: EventReader<DeathEvent>,
    mut commander_death_events: EventWriter<CommanderDeathEvent>,
    commanders: Query<&Commander>,
) {
    for event in death_events.read() {
        if commanders.contains(event.entity) {
            // Create a commander-specific death event
            commander_death_events.send(CommanderDeathEvent {
                commander: event.entity,
                controller: event.controller,
                cause: event.cause.clone(),
            });
        }
    }
}

/// Event for when a commander dies
#[derive(Event)]
pub struct CommanderDeathEvent {
    /// The commander that died
    pub commander: Entity,
    /// The controller of the commander
    pub controller: Entity,
    /// What caused the death
    pub cause: DeathCause,
}

/// System that handles the option to put commander in command zone instead of graveyard
pub fn handle_commander_zone_choice(
    mut commands: Commands,
    mut death_events: EventReader<DeathEvent>,
    mut zone_choice_events: EventWriter<CommanderZoneChoiceEvent>,
    commanders: Query<&Commander>,
    owners: Query<&Owner>,
) {
    for event in death_events.read() {
        if commanders.contains(event.entity) {
            if let Ok(owner) = owners.get(event.entity) {
                // Create a zone choice event for the commander's owner
                zone_choice_events.send(CommanderZoneChoiceEvent {
                    commander: event.entity,
                    owner: owner.0,
                    source_zone: Zone::Battlefield,
                    destination_options: vec![Zone::Graveyard, Zone::Command],
                });
            }
        }
    }
}
}

Lieutenant Triggers

"Lieutenant" is a Commander-specific mechanic that gives bonuses when you control your commander:

#![allow(unused)]
fn main() {
/// Component for Lieutenant abilities
#[derive(Component)]
pub struct Lieutenant {
    /// The effect that happens when you control your commander
    pub effect: Box<dyn LieutenantEffect>,
}

/// System that checks for and applies Lieutenant effects
pub fn check_lieutenant_condition(
    mut commands: Commands,
    lieutenant_cards: Query<(Entity, &Lieutenant, &Controller)>,
    battlefield: Query<(Entity, &Controller), With<OnBattlefield>>,
    commanders: Query<(Entity, &Commander)>,
) {
    // For each card with a Lieutenant ability
    for (lieutenant_entity, lieutenant, controller) in lieutenant_cards.iter() {
        // Check if controller controls their commander on the battlefield
        let controls_commander = battlefield
            .iter()
            .filter(|(entity, card_controller)| {
                // Must be controlled by same player as Lieutenant card
                card_controller.0 == controller.0 &&
                // Must be a commander
                commanders.contains(*entity)
            })
            .count() > 0;
        
        // Apply or remove the Lieutenant effect based on condition
        if controls_commander {
            // Apply the effect if not already applied
            if !commands.entity(lieutenant_entity).contains::<ActiveLieutenantEffect>() {
                commands.entity(lieutenant_entity).insert(ActiveLieutenantEffect);
                lieutenant.effect.apply(commands.world_mut(), lieutenant_entity);
            }
        } else {
            // Remove the effect if it was applied
            if commands.entity(lieutenant_entity).contains::<ActiveLieutenantEffect>() {
                commands.entity(lieutenant_entity).remove::<ActiveLieutenantEffect>();
                lieutenant.effect.remove(commands.world_mut(), lieutenant_entity);
            }
        }
    }
}

/// Marker component for entities with active Lieutenant effects
#[derive(Component)]
pub struct ActiveLieutenantEffect;
}

Partner Triggers

Partner commanders have unique triggered abilities:

#![allow(unused)]
fn main() {
/// Component for "Partner with" tutor ability
#[derive(Component)]
pub struct PartnerWithTutorAbility {
    /// The name of the partner card to search for
    pub partner_name: String,
}

/// System that handles the "Partner with" tutor trigger
pub fn handle_partner_tutor_trigger(
    mut commands: Commands,
    mut entered_battlefield_events: EventReader<EnteredBattlefieldEvent>,
    partner_tutors: Query<(Entity, &PartnerWithTutorAbility, &Controller)>,
    mut tutor_events: EventWriter<TutorEvent>,
) {
    for event in entered_battlefield_events.read() {
        if let Ok((entity, tutor, controller)) = partner_tutors.get(event.entity) {
            // Create a tutor event to find the partner
            tutor_events.send(TutorEvent {
                player: controller.0,
                card_name: tutor.partner_name.clone(),
                destination_zone: Zone::Hand,
                source: entity,
                optional: true,
            });
        }
    }
}
}

Commander Damage Triggers

Commander damage has a specific trigger at 21 damage:

#![allow(unused)]
fn main() {
/// System that checks for lethal commander damage
pub fn check_commander_damage(
    mut commands: Commands,
    mut damage_events: EventReader<CommanderDamageEvent>,
    mut defeat_events: EventWriter<PlayerDefeatEvent>,
    commander_damage: Query<&CommanderDamageTracker>,
) {
    for event in damage_events.read() {
        // Get damage tracker for the damaged player
        if let Ok(damage_tracker) = commander_damage.get(event.damaged_player) {
            // Check if any commander has dealt 21+ damage
            for (commander, damage) in damage_tracker.damage.iter() {
                if *damage >= 21 {
                    // Player is defeated by commander damage
                    defeat_events.send(PlayerDefeatEvent {
                        player: event.damaged_player,
                        defeat_reason: DefeatReason::CommanderDamage {
                            commander: *commander,
                        },
                    });
                    
                    break;
                }
            }
        }
    }
}
}

Multiplayer-Specific Triggers

Commander's multiplayer nature leads to unique triggered abilities:

#![allow(unused)]
fn main() {
/// Component for "attack trigger" abilities that scale with number of opponents attacked
#[derive(Component)]
pub struct AttackTriggeredAbility {
    /// The effect to apply
    pub effect: Box<dyn AttackEffect>,
    /// Multiplier for multi-opponent attacks
    pub scales_with_opponents: bool,
}

/// System that handles attack triggers in multiplayer
pub fn handle_attack_triggers(
    mut commands: Commands,
    mut attack_events: EventReader<AttackEvent>,
    attack_abilities: Query<(Entity, &AttackTriggeredAbility, &Controller)>,
) {
    // Group attacks by controller to count unique opponents
    let mut controller_attacks: HashMap<Entity, HashSet<Entity>> = HashMap::new();
    
    for event in attack_events.read() {
        if let Ok(attacker_controller) = controllers.get(event.attacker) {
            controller_attacks
                .entry(attacker_controller.0)
                .or_default()
                .insert(event.defender);
        }
    }
    
    // Trigger abilities based on attacks
    for (ability_entity, ability, controller) in attack_abilities.iter() {
        if let Some(attacked_opponents) = controller_attacks.get(&controller.0) {
            if !attacked_opponents.is_empty() {
                if ability.scales_with_opponents {
                    // Apply effect with scaling factor
                    let scale_factor = attacked_opponents.len() as i32;
                    ability.effect.apply_scaled(
                        commands.world_mut(), 
                        ability_entity, 
                        scale_factor
                    );
                } else {
                    // Apply effect normally
                    ability.effect.apply(commands.world_mut(), ability_entity);
                }
            }
        }
    }
}
}

Testing Commander Triggers

Testing Commander-specific triggers requires special test fixtures:

#![allow(unused)]
fn main() {
#[test]
fn test_lieutenant_trigger() {
    let mut app = App::new();
    setup_test_game(&mut app);
    
    // Create a player
    let player = app.world.spawn(Player).id();
    
    // Create a commander in the command zone
    let commander = app.world.spawn((
        CardName("Test Commander".to_string()),
        Commander,
        Controller(player),
    )).id();
    
    // Create a card with Lieutenant ability
    let lieutenant = app.world.spawn((
        CardName("Test Lieutenant".to_string()),
        OnBattlefield,
        Controller(player),
        Lieutenant {
            effect: Box::new(TestLieutenantEffect),
        },
    )).id();
    
    // Run the lieutenant check system
    app.update();
    
    // Initially, commander not on battlefield, so no effect
    assert!(!app.world.entity(lieutenant).contains::<ActiveLieutenantEffect>());
    
    // Move commander to battlefield
    app.world.entity_mut(commander).insert(OnBattlefield);
    
    // Run the lieutenant check system again
    app.update();
    
    // Now the effect should be active
    assert!(app.world.entity(lieutenant).contains::<ActiveLieutenantEffect>());
    
    // Remove commander from battlefield
    app.world.entity_mut(commander).remove::<OnBattlefield>();
    
    // Run system again
    app.update();
    
    // Effect should be removed
    assert!(!app.world.entity(lieutenant).contains::<ActiveLieutenantEffect>());
}
}

Integration with Core Triggered Abilities

Commander-specific triggered abilities integrate with the core triggered ability system:

#![allow(unused)]
fn main() {
pub fn register_commander_triggered_abilities(app: &mut App) {
    app
        .add_event::<CommanderDeathEvent>()
        .add_event::<CommanderZoneChoiceEvent>()
        .add_systems(Update, (
            handle_command_zone_triggers,
            handle_commander_death_triggers,
            handle_commander_zone_choice,
            check_lieutenant_condition,
            handle_partner_tutor_trigger,
            check_commander_damage,
            handle_attack_triggers,
        ).after(CoreTriggerSystems));
}
}

Related Resources

• Commander Death Triggers
• Partner Commanders
• Commander Damage
• Command Zone
• Core Triggered Abilities Documentation

Random Elements in Commander

This document outlines how random elements in Magic: The Gathering are implemented in the Commander format within Rummage.

Types of Random Elements

Magic: The Gathering contains several types of random elements that require implementation in a digital engine:

Implementation Approach

In Rummage, we implement random elements using a deterministic RNG system that:

1. Maintains synchronization across networked games
2. Provides verifiable randomness that can be audited
3. Seeds random generators consistently across client instances
4. Allows for replaying game states with identical outcomes

Code Example: Deterministic RNG

#![allow(unused)]
fn main() {
use bevy::prelude::*;
use rand::{Rng, SeedableRng};
use rand_chacha::ChaCha8Rng;

#[derive(Resource)]
pub struct GameRng(ChaCha8Rng);

impl GameRng {
    pub fn new_seeded(seed: u64) -> Self {
        Self(ChaCha8Rng::seed_from_u64(seed))
    }
    
    pub fn flip_coin(&mut self) -> bool {
        self.0.gen_bool(0.5)
    }
    
    pub fn roll_die(&mut self, sides: u32) -> u32 {
        self.0.gen_range(1..=sides)
    }
    
    pub fn select_random_index(&mut self, max: usize) -> usize {
        if max == 0 {
            return 0;
        }
        self.0.gen_range(0..max)
    }
}

// System that handles coin flips
fn handle_coin_flip(
    mut commands: Commands,
    mut rng: ResMut<GameRng>,
    mut coin_flip_events: EventReader<CoinFlipEvent>,
) {
    for event in coin_flip_events.read() {
        let result = rng.flip_coin();
        commands.spawn(CoinFlipResult {
            source: event.source,
            result,
            affected_entities: event.affected_entities.clone(),
        });
    }
}
}

Synchronization with Multiplayer

In multiplayer Commander games, random outcomes must be identical for all players. To achieve this:

1. The host acts as the source of truth for RNG seed
2. RNG state is included in the synchronized game state
3. Random events are processed deterministically
4. Network desync detection checks RNG state

Testing Random Elements

Random elements require special testing approaches:

1. Seeded Tests: Using known seeds to produce predictable outcomes
2. Distribution Tests: Verifying statistical properties over many trials
3. Edge Case Tests: Testing boundary conditions and extreme outcomes
4. Determinism Tests: Ensuring identical outcomes given the same seed

Example Test

#![allow(unused)]
fn main() {
#[test]
fn test_coin_flip_determinism() {
    // Create two RNGs with the same seed
    let mut rng1 = GameRng::new_seeded(12345);
    let mut rng2 = GameRng::new_seeded(12345);
    
    // They should produce identical sequences
    for _ in 0..100 {
        assert_eq!(rng1.flip_coin(), rng2.flip_coin());
    }
}
}

Commander-Specific Concerns

In Commander, random elements interact with multiplayer politics in unique ways:

1. Perception of fairness in random outcomes
2. Impact of random effects on multiple players simultaneously
3. Using random outcomes as leverage in political negotiations
4. Varying player attitudes toward randomness and luck

Our implementation supports these dynamics by:

• Providing clear visualization of random processes
• Implementing rules for modifying random outcomes (like Krark's Thumb)
• Supporting multiplayer-specific random effects
• Allowing customization of random elements in house rules

Summary

Random elements in Commander are implemented using deterministic, network-synchronized systems that maintain game integrity while supporting the unique social and political dynamics of the format.

Game State Management

Overview

The Game State Management module is responsible for tracking and maintaining the complete state of a Commander game. It serves as the central source of truth for all game data and coordinates the interactions between other modules, ensuring rules compliance according to the Magic: The Gathering Comprehensive Rules section 903.

Core Components

GameState Resource

#![allow(unused)]
fn main() {
#[derive(Resource)]
pub struct CommanderGameState {
    // Game metadata
    pub game_id: uuid::Uuid,
    pub turn_number: u32,
    pub start_time: std::time::Instant,
    
    // Active player and turn state
    pub active_player_index: usize,
    pub player_order: Vec<Entity>,
    pub current_phase: Phase,
    pub priority_holder: Entity,
    
    // Game parameters
    pub starting_life: u32,  // 40 for Commander (rule 903.7)
    pub max_players: u8,     // Up to 13 supported
    pub commander_damage_threshold: u32,  // 21 (rule 903.10a)
    
    // Game state flags
    pub is_game_over: bool,
    pub winner: Option<Entity>,
    
    // Special Commander format states
    pub commander_cast_count: HashMap<Entity, u32>,  // For commander tax
    pub eliminated_players: Vec<Entity>,
}
}

State Tracking Components

#![allow(unused)]
fn main() {
#[derive(Component)]
pub struct CommanderGameParticipant {
    pub player_index: usize,
    pub is_active: bool,
}

#[derive(Component)]
pub struct TurnOrderPosition {
    pub position: usize,
    pub is_skipping_turn: bool,
}

#[derive(Component, Default)]
pub struct GameStateFlags {
    pub has_played_land: bool,
    pub commanders_in_play: HashSet<Entity>,
    pub has_attacked_this_turn: bool,
}
}

Key Systems

Game State Initialization

#![allow(unused)]
fn main() {
pub fn initialize_commander_game(
    mut commands: Commands,
    mut game_state: ResMut<CommanderGameState>,
    players: Query<Entity, With<Player>>,
) {
    // Set up initial game state
    game_state.game_id = uuid::Uuid::new_v4();
    game_state.turn_number = 1;
    game_state.start_time = std::time::Instant::now();
    
    // Set up player order (randomized)
    let mut player_entities = players.iter().collect::<Vec<_>>();
    player_entities.shuffle(&mut rand::thread_rng());
    game_state.player_order = player_entities;
    
    // Set initial active player
    game_state.active_player_index = 0;
    game_state.priority_holder = player_entities[0];
    
    // Set starting phase
    game_state.current_phase = Phase::Beginning(BeginningPhaseStep::Untap);
    
    // Initialize Commander-specific parameters
    game_state.starting_life = 40;  // Commander rule 903.7
    game_state.commander_damage_threshold = 21;  // Commander rule 903.10a
    
    // Tag entities with player index
    for (idx, entity) in player_entities.iter().enumerate() {
        commands.entity(*entity).insert(CommanderGameParticipant {
            player_index: idx,
            is_active: idx == 0,
        });
        
        commands.entity(*entity).insert(TurnOrderPosition {
            position: idx,
            is_skipping_turn: false,
        });
        
        commands.entity(*entity).insert(GameStateFlags::default());
    }
}
}

Game State Update System

#![allow(unused)]
fn main() {
pub fn update_game_state(
    mut game_state: ResMut<CommanderGameState>,
    mut players: Query<(Entity, &mut CommanderGameParticipant, &PlayerState)>,
    time: Res<Time>,
) {
    // Check for eliminated players
    for (entity, participant, state) in players.iter() {
        if state.life_total <= 0 && !game_state.eliminated_players.contains(&entity) {
            game_state.eliminated_players.push(entity);
        }
    }
    
    // Check for game over condition
    let remaining_players = players
        .iter()
        .filter(|(entity, _, _)| !game_state.eliminated_players.contains(&entity))
        .count();
    
    if remaining_players <= 1 {
        game_state.is_game_over = true;
        if remaining_players == 1 {
            let winner = players
                .iter()
                .find(|(entity, _, _)| !game_state.eliminated_players.contains(&entity))
                .map(|(entity, _, _)| entity);
            game_state.winner = winner;
        }
    }
}
}

State Validation

The game state management module includes validation functions to ensure game state consistency:

#![allow(unused)]
fn main() {
pub fn validate_game_state(game_state: &CommanderGameState) -> Result<(), String> {
    // Validate player count
    if game_state.player_order.is_empty() {
        return Err("Game must have at least one player".to_string());
    }
    
    if game_state.player_order.len() > game_state.max_players as usize {
        return Err(format!("Game cannot have more than {} players", game_state.max_players));
    }
    
    // Validate active player
    if game_state.active_player_index >= game_state.player_order.len() {
        return Err("Active player index out of bounds".to_string());
    }
    
    // More validations...
    
    Ok(())
}
}

Integration Points

The game state module integrates with other systems through:

1. Resource access - Other systems can read the game state
2. Events - Game state changes trigger events for other systems
3. Commands - Game state can be updated through commands

This module forms the foundation of the Commander game engine, providing the central state management needed to coordinate all other game systems.

Random Mechanics Test Cases

Overview

This document outlines test cases for Magic: The Gathering cards and mechanics involving randomness, including coin flips, dice rolls, and random selections. When implementing these mechanics, it's crucial to ensure deterministic testing while maintaining fair randomness in actual gameplay.

Randomness in Commander Format

The Commander format includes many cards with random elements that require special handling:

1. Commander-Specific Random Cards: Many popular Commander cards use coin flips, dice rolls, or random selection as a core mechanic (e.g., Okaun, Eye of Chaos, Zndrsplt, Eye of Wisdom, Yusri, Fortune's Flame)

2. Multiplayer Considerations: Random effects in multiplayer games need to ensure all players can verify the randomness

3. Deterministic Testing: While gameplay should be truly random, our testing requires deterministic outcomes

4. Network Implementation: In networked games, random results must be synchronized across all clients

This document provides test cases to ensure these mechanics work properly within the Commander format implementation.

Test Principles

1. Deterministic Testing: All random operations must be mockable for testing
2. Seed Control: Tests should use fixed seeds for reproducibility
3. Distribution Validation: Test that random operations have the expected distribution over many trials
4. User Interface: Test that random events are properly communicated to players

Coin Flip Test Cases

Basic Coin Flip Mechanics

#![allow(unused)]
fn main() {
#[test]
fn test_basic_coin_flip() {
    // Create a test game with mocked RNG using a predetermined seed
    let mut game = TestGame::new_with_seed(12345);
    
    // Add Krark's Thumb to player 1's battlefield
    // "If you would flip a coin, instead flip two coins and ignore one of them."
    game.add_card_to_battlefield(1, "Krark's Thumb");
    
    // Add Chance Encounter to player 1's battlefield
    // "Whenever you win a coin flip, put a luck counter on Chance Encounter.
    // At the beginning of your upkeep, if Chance Encounter has ten or more luck counters on it, you win the game."
    game.add_card_to_battlefield(1, "Chance Encounter");
    
    // Cast Stitch in Time
    // "Flip a coin. If you win the flip, take an extra turn after this one."
    game.cast_spell(1, "Stitch in Time");
    
    // Verify the coin flip sequence was triggered
    assert!(game.event_occurred(GameEvent::CoinFlipStarted));
    
    // With our test seed, we know the first flip should be a win
    // and the second flip would be a loss, but Krark's Thumb lets us ignore one
    assert_eq!(game.get_extra_turns_count(1), 1);
    
    // A luck counter should be added to Chance Encounter
    assert_eq!(game.get_counters(Card::by_name("Chance Encounter"), CounterType::Luck), 1);
}
}

Commander with Coin Flip Abilities

#![allow(unused)]
fn main() {
#[test]
fn test_okaun_zndrsplt_interaction() {
    // Create a test game with mocked RNG
    let mut game = TestGame::new_with_seed(42);
    
    // Add Okaun, Eye of Chaos and Zndrsplt, Eye of Wisdom as commanders for player 1
    // Okaun: "Whenever you win a coin flip, double Okaun's power and toughness until end of turn."
    // Zndrsplt: "Whenever you win a coin flip, draw a card."
    game.add_commander(1, "Okaun, Eye of Chaos");
    game.add_commander(1, "Zndrsplt, Eye of Wisdom");
    
    // Cast Frenetic Efreet
    // "{0}: Flip a coin. If you win the flip, Frenetic Efreet phases out.
    // If you lose the flip, sacrifice Frenetic Efreet."
    game.cast_spell(1, "Frenetic Efreet");
    
    // Activate ability three times, with predetermined results: win, lose, win
    game.set_next_coin_flips([true, false, true]);
    
    for _ in 0..3 {
        game.activate_ability(Card::by_name("Frenetic Efreet"), 0);
        game.resolve_stack();
    }
    
    // Verify Okaun's power/toughness was doubled twice (for two wins)
    // Base P/T is 3/3, doubled twice = 12/12
    let okaun = game.get_battlefield_card(1, "Okaun, Eye of Chaos");
    assert_eq!(game.get_power(okaun), 12);
    assert_eq!(game.get_toughness(okaun), 12);
    
    // Verify player drew 2 cards from Zndrsplt's ability
    assert_eq!(game.get_hand_size(1), 2);
    
    // Verify Frenetic Efreet was sacrificed on the loss
    assert!(game.in_graveyard(Card::by_name("Frenetic Efreet")));
}
}

Edge Cases

#![allow(unused)]
fn main() {
#[test]
fn test_coin_flip_replacement_effects() {
    let mut game = TestGame::new_with_seed(7777);
    
    // Add Krark's Thumb to player 1's battlefield
    game.add_card_to_battlefield(1, "Krark's Thumb");
    
    // Add Goblin Archaeologist to battlefield
    // "{T}: Flip a coin. If you win the flip, destroy target artifact.
    // If you lose the flip, sacrifice Goblin Archaeologist."
    game.add_card_to_battlefield(1, "Goblin Archaeologist");
    
    // Add a target artifact
    game.add_card_to_battlefield(2, "Sol Ring");
    
    // Add Chance Encounter
    game.add_card_to_battlefield(1, "Chance Encounter");
    
    // Add Tavern Scoundrel
    // "Whenever you win one or more coin flips, create a Treasure token."
    game.add_card_to_battlefield(1, "Tavern Scoundrel");
    
    // Setup test for replacement effect - ensure both flips are a "win"
    game.set_next_coin_flips([true, true]);
    
    // Activate Goblin Archaeologist targeting Sol Ring
    game.activate_ability_with_target(
        Card::by_name("Goblin Archaeologist"), 
        0, 
        Card::by_name("Sol Ring")
    );
    game.resolve_stack();
    
    // Verify Sol Ring was destroyed
    assert!(game.in_graveyard(Card::by_name("Sol Ring")));
    
    // Verify Goblin Archaeologist is still on the battlefield
    assert!(game.on_battlefield(Card::by_name("Goblin Archaeologist")));
    
    // Verify we got only ONE Treasure token despite flipping two coins
    // (Tavern Scoundrel triggers on "one or more" wins, not per win)
    assert_eq!(game.count_permanents_by_type(1, "Treasure"), 1);
    
    // Verify Chance Encounter got a luck counter
    assert_eq!(game.get_counters(Card::by_name("Chance Encounter"), CounterType::Luck), 1);
}
}

Dice Rolling Test Cases

Basic Dice Rolling

#![allow(unused)]
fn main() {
#[test]
fn test_basic_dice_rolling() {
    let mut game = TestGame::new_with_seed(42);
    
    // Add Delina, Wild Mage to battlefield
    // "Whenever Delina, Wild Mage attacks, roll a d20. If you roll a 15 or higher, 
    // create a token that's a copy of target creature you control..."
    game.add_card_to_battlefield(1, "Delina, Wild Mage");
    
    // Add a target creature
    game.add_card_to_battlefield(1, "Llanowar Elves");
    
    // Set up attack
    game.begin_combat();
    game.declare_attacker(Card::by_name("Delina, Wild Mage"), 2);
    
    // Mock the d20 roll to be 17
    game.set_next_dice_roll(20, 17);
    
    // Resolve Delina's triggered ability, targeting Llanowar Elves
    game.choose_target_for_ability(
        Card::by_name("Delina, Wild Mage"), 
        Card::by_name("Llanowar Elves")
    );
    game.resolve_stack();
    
    // Verify a token copy was created
    assert_eq!(game.count_permanents_by_name(1, "Llanowar Elves"), 2);
    
    // Verify the token has haste (part of Delina's ability)
    let token = game.get_tokens_by_name(1, "Llanowar Elves")[0];
    assert!(game.has_ability(token, Ability::Haste));
}
}

Commander With Dice Rolling Abilities

#![allow(unused)]
fn main() {
#[test]
fn test_farideh_commander() {
    let mut game = TestGame::new_with_seed(42);
    
    // Add Farideh, Devil's Chosen as commander for player 1
    // "Whenever you roll one or more dice, Farideh, Devil's Chosen gains flying and menace until end of turn.
    // Whenever you roll a natural 20 on a d20, put a +1/+1 counter on Farideh."
    game.add_commander(1, "Farideh, Devil's Chosen");
    
    // Cast Pixie Guide
    // "If you would roll a d20, instead roll two d20s and use the higher roll."
    game.cast_spell(1, "Pixie Guide");
    
    // Cast Light of Hope
    // "Roll a d20. If you roll a 1-9, create a 3/3 Angel creature token with flying.
    // If you roll a 10-19, you gain 3 life for each creature you control.
    // If you roll a 20, until end of turn, creatures you control gain +2/+2 and acquire flying."
    game.cast_spell(1, "Light of Hope");
    
    // Set dice rolls to 8 and 20 (Pixie Guide will use the 20)
    game.set_next_dice_rolls(20, [8, 20]);
    game.resolve_stack();
    
    // Verify the abilities triggered by the natural 20
    // 1. Creatures get +2/+2 and flying from Light of Hope
    // 2. Farideh gets a +1/+1 counter from her ability
    // 3. Farideh gets flying and menace from her first ability
    
    // Check Farideh's power/toughness (base 3/3 + 1 counter + 2 from Light of Hope = 6/6)
    let farideh = game.get_battlefield_card(1, "Farideh, Devil's Chosen");
    assert_eq!(game.get_power(farideh), 6);
    assert_eq!(game.get_toughness(farideh), 6);
    assert_eq!(game.get_counters(farideh, CounterType::PlusOnePlusOne), 1);
    
    // Check abilities
    assert!(game.has_ability(farideh, Ability::Flying));
    assert!(game.has_ability(farideh, Ability::Menace));
    
    // Pixie Guide should also have +2/+2 and flying from Light of Hope
    let pixie = game.get_battlefield_card(1, "Pixie Guide");
    assert_eq!(game.get_power(pixie), game.get_base_power(pixie) + 2);
    assert!(game.has_ability(pixie, Ability::Flying));
}
}

Random Selection Test Cases

Random Discard

#![allow(unused)]
fn main() {
#[test]
fn test_random_discard() {
    let mut game = TestGame::new_with_seed(42);
    
    // Set up player 2's hand with known cards
    let cards = ["Island", "Lightning Bolt", "Dark Ritual", "Divination", "Doom Blade"];
    for card in cards {
        game.add_card_to_hand(2, card);
    }
    
    // Cast Hypnotic Specter with player 1
    game.add_card_to_battlefield(1, "Hypnotic Specter");
    
    // Deal damage to trigger discard
    game.deal_damage(Card::by_name("Hypnotic Specter"), Player(2), 1);
    
    // Set up the random discard to choose Lightning Bolt
    game.set_next_random_card_index(1); // 0-indexed, so this is the second card
    game.resolve_stack();
    
    // Verify Lightning Bolt was discarded
    assert!(game.in_graveyard(Card::by_name("Lightning Bolt")));
    assert_eq!(game.get_hand_size(2), 4);
}
}

Random Target Selection

#![allow(unused)]
fn main() {
#[test]
fn test_random_target_selection() {
    let mut game = TestGame::new_with_seed(42);
    
    // Setup battlefield with multiple creatures
    game.add_card_to_battlefield(2, "Grizzly Bears");
    game.add_card_to_battlefield(2, "Hill Giant");
    game.add_card_to_battlefield(2, "Shivan Dragon");
    
    // Cast Confusion in the Ranks with player 1
    // "Whenever a permanent enters the battlefield, its controller chooses target permanent 
    // another player controls that shares a type with it. Exchange control of those permanents."
    game.add_card_to_battlefield(1, "Confusion in the Ranks");
    
    // Cast Mogg Fanatic (creature)
    game.cast_spell(1, "Mogg Fanatic");
    
    // Mogg Fanatic enters, triggering Confusion in the Ranks
    // Set the random target to be Hill Giant (index 1 of the 3 valid targets)
    game.set_next_random_target_index(1);
    game.resolve_stack();
    
    // Verify Hill Giant is now controlled by player 1
    assert_eq!(game.get_controller(Card::by_name("Hill Giant")), Player(1));
    
    // Verify Mogg Fanatic is now controlled by player 2
    assert_eq!(game.get_controller(Card::by_name("Mogg Fanatic")), Player(2));
}
}

Integration with Commander Rules

Commander Damage with Chaotic Strike

#![allow(unused)]
fn main() {
#[test]
fn test_commander_damage_with_random_double_strike() {
    let mut game = TestGame::new_with_seed(42);
    
    // Setup Player 1's commander
    game.add_commander(1, "Gisela, Blade of Goldnight");
    
    // Cast Chaos Warp targeting an unimportant permanent
    // "The owner of target permanent shuffles it into their library, 
    // then reveals the top card of their library. If it's a permanent card, 
    // they put it onto the battlefield."
    game.add_card_to_hand(1, "Chaos Warp");
    game.cast_spell_with_target(1, "Chaos Warp", Card::by_name("Forest"));
    
    // Set up the random reveal to be Berserker's Onslaught
    // "Attacking creatures you control have double strike."
    game.set_next_reveal_card("Berserker's Onslaught");
    game.resolve_stack();
    
    // Move to combat
    game.begin_combat();
    game.declare_attacker(Card::by_name("Gisela, Blade of Goldnight"), 2);
    
    // Resolve combat damage
    game.resolve_combat_damage();
    
    // Verify commander damage - should be doubled from Berserker's Onslaught
    // Gisela is a 5/5 flying first strike, so should deal 10 commander damage with double strike
    assert_eq!(game.get_commander_damage(2, Card::by_name("Gisela, Blade of Goldnight")), 10);
}
}

Mock Framework for Testing Random Events

The test cases above reference various functions for mocking random events. Here's an example implementation for the test framework:

#![allow(unused)]
fn main() {
impl TestGame {
    /// Create a new test game with a fixed seed for reproducible randomness
    pub fn new_with_seed(seed: u64) -> Self {
        let mut game = Self::new();
        game.set_rng_seed(seed);
        game
    }
    
    /// Set the results of the next coin flips
    pub fn set_next_coin_flips(&mut self, results: impl Into<Vec<bool>>) {
        self.coin_flip_results = results.into();
    }
    
    /// Set the result of a single upcoming coin flip
    pub fn set_next_coin_flip(&mut self, result: bool) {
        self.coin_flip_results = vec![result];
    }
    
    /// Set the results of the next dice rolls of a specific size (e.g., d20)
    pub fn set_next_dice_rolls(&mut self, sides: u32, results: impl Into<Vec<u32>>) {
        self.dice_roll_results.insert(sides, results.into());
    }
    
    /// Set the result of a single upcoming dice roll
    pub fn set_next_dice_roll(&mut self, sides: u32, result: u32) {
        self.dice_roll_results.insert(sides, vec![result]);
    }
    
    /// Set which card will be chosen in a random selection (by index)
    pub fn set_next_random_card_index(&mut self, index: usize) {
        self.random_card_indices = vec![index];
    }
    
    /// Set which target will be chosen in a random selection (by index)
    pub fn set_next_random_target_index(&mut self, index: usize) {
        self.random_target_indices = vec![index];
    }
    
    /// Set the next card to be revealed from a library
    pub fn set_next_reveal_card(&mut self, card_name: &str) {
        self.next_reveal_cards.push(card_name.to_string());
    }
}
}

Implementation Notes

1. All random operations should be abstracted through an RngService to allow for deterministic testing.
2. The RngService should be injectable and replaceable with a mock version for tests.
3. Test cases should validate both mechanical correctness and expected probabilities.
4. The UI should clearly communicate random events to players, with appropriate animations.

Future Considerations

1. Testing network lag effects on synchronization of random events in multiplayer games
2. Validating fairness of random number generation over large sample sizes
3. Implementing proper security measures to prevent cheating in networked games

Player Mechanics

This section covers player-specific mechanics in the Commander format implementation.

Contents

• Player Management - Player data structures and basic player operations
• Commander Damage - Tracking and implementing the 21-damage rule
• Multiplayer Politics - Voting, deals, and other social mechanics

The player mechanics section defines how players interact within the Commander format, including:

• Starting with 40 life (compared to 20 in standard Magic)
• Commander damage tracking (21+ combat damage from a single commander causes a loss)
• Turn order and priority management in multiplayer
• Special multiplayer interactions like voting, monarch status, and political deals
• Player elimination and handling of player-owned objects after elimination

These mechanics are essential for correctly implementing the multiplayer aspects of Commander, especially with games supporting between 2 and 13 players.

Life Total Management in Commander

This document covers the implementation of life total management in the Commander format within Rummage.

Commander Life Total Rules

In the Commander format, players have the following life total rules:

1. Starting life total is 40 (compared to 20 in standard Magic)
2. A player loses if their life total is 0 or less
3. A player can gain life above their starting total with no upper limit
4. Life totals are tracked for each player throughout the game
5. There is no life loss from drawing from an empty library (unlike in standard Magic)

Additionally, Commander has a unique "Commander damage" rule:

• A player loses if they've been dealt 21 or more combat damage by a single commander

Implementation

Life Total Component

#![allow(unused)]
fn main() {
/// Component for tracking player life totals
#[derive(Component, Debug, Clone, Reflect)]
pub struct LifeTotal {
    /// Current life value
    pub current: i32,
    /// Starting life value
    pub starting: i32,
    /// Damage taken from each commander (entity ID -> damage amount)
    pub commander_damage: HashMap<Entity, i32>,
}

impl Default for LifeTotal {
    fn default() -> Self {
        Self {
            current: 40, // Commander starts at 40 life
            starting: 40,
            commander_damage: HashMap::new(),
        }
    }
}
}

Life Change Events

#![allow(unused)]
fn main() {
#[derive(Event, Debug, Clone)]
pub enum LifeChangeEvent {
    Gain(Entity, i32),     // (Player entity, amount)
    Loss(Entity, i32),     // (Player entity, amount)
    Set(Entity, i32),      // (Player entity, new value)
    CommanderDamage {
        target: Entity,    // Target player
        source: Entity,    // Commander entity
        amount: i32,       // Damage amount
    },
}
}

Life Total System

#![allow(unused)]
fn main() {
/// System that handles life total changes
pub fn handle_life_changes(
    mut players: Query<(Entity, &mut LifeTotal)>,
    mut life_events: EventReader<LifeChangeEvent>,
    mut game_events: EventWriter<GameEvent>,
) {
    let mut changed_players = HashSet::new();
    
    // Process all life change events
    for event in life_events.read() {
        match event {
            LifeChangeEvent::Gain(entity, amount) => {
                if let Ok((_, mut life)) = players.get_mut(*entity) {
                    life.current += amount;
                    changed_players.insert(*entity);
                }
            },
            LifeChangeEvent::Loss(entity, amount) => {
                if let Ok((_, mut life)) = players.get_mut(*entity) {
                    life.current -= amount;
                    changed_players.insert(*entity);
                }
            },
            LifeChangeEvent::Set(entity, value) => {
                if let Ok((_, mut life)) = players.get_mut(*entity) {
                    life.current = *value;
                    changed_players.insert(*entity);
                }
            },
            LifeChangeEvent::CommanderDamage { target, source, amount } => {
                if let Ok((_, mut life)) = players.get_mut(*target) {
                    let current_damage = life.commander_damage.entry(*source).or_insert(0);
                    *current_damage += amount;
                    life.current -= amount;
                    changed_players.insert(*target);
                }
            }
        }
    }
    
    // Check for game loss conditions
    for entity in changed_players {
        if let Ok((player_entity, life)) = players.get(entity) {
            // Check for zero or less life
            if life.current <= 0 {
                game_events.send(GameEvent::PlayerLost {
                    player: player_entity,
                    reason: LossReason::LifeTotal,
                });
            }
            
            // Check for commander damage
            for (cmdr, damage) in &life.commander_damage {
                if *damage >= 21 {
                    game_events.send(GameEvent::PlayerLost {
                        player: player_entity,
                        reason: LossReason::CommanderDamage(*cmdr),
                    });
                    break;
                }
            }
        }
    }
}
}

Life Gain/Loss Display

In the UI, life total changes are displayed with:

1. Animated counters that show the direction and amount of life change
2. Color-coded visual feedback (green for gain, red for loss)
3. Persistent life total display for all players
4. Visual warning when a player is at low life
5. Commander damage trackers for each opponent's commander

Life Total Interactions

Various cards and effects can interact with life totals:

1. Life gain/loss effects: Direct modification of life totals
2. Life total setting effects: Cards that set life to a specific value
3. Life swapping effects: Cards that exchange life totals between players
4. Damage redirection: Effects that redirect damage from one player to another
5. Damage prevention: Effects that prevent damage that would be dealt

Testing Life Total Management

We test life total functionality with:

1. Unit tests: Verifying the baseline functionality
2. Integration tests: Testing interactions with damage effects
3. Edge case tests: Testing boundary conditions (very high/low life totals)
4. Visual tests: Verifying the UI correctly displays life changes

Example Test

#![allow(unused)]
fn main() {
#[test]
fn test_commander_damage_loss() {
    // Create a test app with required systems
    let mut app = App::new();
    app.add_systems(Update, handle_life_changes)
        .add_event::<LifeChangeEvent>()
        .add_event::<GameEvent>();
        
    // Create player entities
    let player = app.world.spawn(LifeTotal::default()).id();
    let commander = app.world.spawn_empty().id();
    
    // Deal 21 commander damage
    app.world.send_event(LifeChangeEvent::CommanderDamage {
        target: player,
        source: commander,
        amount: 21,
    });
    
    // Run systems
    app.update();
    
    // Check if loss event was sent
    let events = app.world.resource::<Events<GameEvent>>();
    let mut reader = events.get_reader();
    let mut found_loss = false;
    
    for event in reader.read(&events) {
        if let GameEvent::PlayerLost { player: p, reason: LossReason::CommanderDamage(cmdr) } = event {
            if *p == player && *cmdr == commander {
                found_loss = true;
                break;
            }
        }
    }
    
    assert!(found_loss, "Player should lose to commander damage");
}
}

Summary

Life total management in Commander is implemented with a flexible system that:

1. Correctly applies the Commander-specific starting life total of 40
2. Tracks commander damage separately from regular life changes
3. Implements all standard and Commander-specific loss conditions
4. Provides clear visual feedback through the UI
5. Supports all card interactions with life totals

Commander Tax

This document explains the implementation of the Commander Tax mechanic in the Rummage game engine.

Overview

Commander Tax is a core rule of the Commander format that increases the cost to cast your commander from the command zone by {2} for each previous time you've cast it from the command zone during the game.

The rule ensures that:

1. Players cannot repeatedly abuse their commander's abilities by letting it die and recasting it
2. The game becomes progressively more challenging as players need to invest more mana into recasting their commander
3. Decks need to consider their commander's mana value when building their strategy

Formula

The cost to cast a commander is calculated as:

Total Cost = Base Cost + (2 × Number of Previous Casts)

For example:

• First cast: Base cost
• Second cast: Base cost + {2}
• Third cast: Base cost + {4}
• Fourth cast: Base cost + {6}

Implementation

Commander Component

#![allow(unused)]
fn main() {
/// Component for commanders
#[derive(Component, Debug, Clone, Reflect)]
pub struct Commander {
    /// Entity ID of the player who owns this commander
    pub owner: Entity,
    /// Number of times this commander has been cast from the command zone
    pub cast_count: u32,
    /// Whether this commander is in the command zone
    pub in_command_zone: bool,
}

impl Default for Commander {
    fn default() -> Self {
        Self {
            owner: Entity::PLACEHOLDER,
            cast_count: 0,
            in_command_zone: true,
        }
    }
}
}

Commander Tax Calculation

#![allow(unused)]
fn main() {
/// Calculates the total cost to cast a commander
pub fn calculate_commander_cost(
    base_cost: Mana,
    commander: &Commander,
) -> Mana {
    // Apply commander tax: 2 generic mana for each previous cast
    let tax_amount = commander.cast_count * 2;
    
    // Create a new mana cost with additional generic mana
    let mut total_cost = base_cost.clone();
    total_cost.colorless += tax_amount;
    
    total_cost
}
}

Casting System

#![allow(unused)]
fn main() {
/// System to handle commander casting
pub fn handle_commander_casting(
    mut commands: Commands,
    mut commanders: Query<(Entity, &mut Commander, &CardCost)>,
    mut cast_events: EventReader<CastCommanderEvent>,
    mut mana_events: EventWriter<ManaCostEvent>,
) {
    for event in cast_events.read() {
        if let Ok((entity, mut commander, cost)) = commanders.get_mut(event.commander) {
            // Calculate total cost with commander tax
            let total_cost = calculate_commander_cost(cost.mana.clone(), &commander);
            
            // Send event to check if player can pay the cost
            mana_events.send(ManaCostEvent {
                player: commander.owner,
                source: entity,
                cost: total_cost,
                on_paid: CastEffect::Commander { entity },
            });
            
            // Increment cast count for next time
            if event.successful {
                commander.cast_count += 1;
                commander.in_command_zone = false;
            }
        }
    }
}
}

Commander Tax Tracking

The UI displays the current commander tax for each player's commander:

1. Current cast count is shown next to the commander in the command zone
2. The additional cost is displayed when hovering over the commander in the command zone
3. The total cost (base + tax) is shown when attempting to cast the commander

Special Interactions

Tax Reduction Effects

Some cards can reduce the commander tax:

#![allow(unused)]
fn main() {
/// Component for effects that reduce commander tax
#[derive(Component, Debug, Clone, Reflect)]
pub struct CommanderTaxReduction {
    /// Amount to reduce the tax by
    pub amount: u32,
    /// Whether this applies to all commanders or specific ones
    pub targets: CommanderTaxReductionTarget,
}

/// Different types of tax reduction targets
#[derive(Debug, Clone, Reflect)]
pub enum CommanderTaxReductionTarget {
    /// Applies to all of your commanders
    AllOwn,
    /// Applies to all commanders (including opponents')
    All,
    /// Applies to specific commanders
    Specific(Vec<Entity>),
}
}

Partner Commanders

Partner commanders track their tax separately:

#![allow(unused)]
fn main() {
/// When checking if a player has a partner commander
pub fn handle_partner_commander_tax(
    partners: Query<(Entity, &Commander, &Partner)>,
    // ... other parameters
) {
    // Each partner tracks its own commander tax separately
    // ...
}
}

Testing

Test Cases

We test the commander tax mechanics with:

1. Basic Tax Progression: Verify tax increases correctly with each cast
2. Tax After Zone Changes: Ensure tax only increases when cast from command zone
3. Tax Reduction Effects: Test cards that reduce commander tax
4. Partner Commander Interaction: Verify partners track tax separately

Example Test

#![allow(unused)]
fn main() {
#[test]
fn test_commander_tax_progression() {
    // Set up test environment
    let mut app = App::new();
    app.add_systems(Update, handle_commander_casting)
        .add_event::<CastCommanderEvent>()
        .add_event::<ManaCostEvent>();
    
    // Create a player and commander
    let player = app.world.spawn_empty().id();
    let base_cost = Mana::new(2, 1, 0, 0, 0, 0); // 2G
    
    let commander = app.world.spawn((
        Commander {
            owner: player,
            cast_count: 0,
            in_command_zone: true,
        },
        CardCost { mana: base_cost.clone() },
    )).id();
    
    // First cast (should be base cost)
    app.world.send_event(CastCommanderEvent {
        commander,
        successful: true,
    });
    app.update();
    
    // Check commander was updated
    let cmdr = app.world.get::<Commander>(commander).unwrap();
    assert_eq!(cmdr.cast_count, 1);
    
    // Second cast (should be base cost + {2})
    app.world.send_event(CastCommanderEvent {
        commander,
        successful: true,
    });
    app.update();
    
    // Verify tax increased
    let cmdr = app.world.get::<Commander>(commander).unwrap();
    assert_eq!(cmdr.cast_count, 2);
    
    // Verify correct cost calculation
    let cmdr = app.world.get::<Commander>(commander).unwrap();
    let total_cost = calculate_commander_cost(base_cost, cmdr);
    assert_eq!(total_cost.colorless, 6); // Base 2 + 4 tax
    assert_eq!(total_cost.green, 1);     // Colored cost unchanged
}
}

Summary

The Commander Tax mechanic in Rummage is implemented as a dynamic cost increase system that:

1. Tracks cast count per commander
2. Applies the correct tax formula
3. Supports complex interactions like cost reduction effects
4. Handles partner commanders appropriately
5. Provides clear UI feedback on current tax amounts

Color Identity in Commander

This document explains how color identity is implemented in the Rummage game engine for the Commander format.

Color Identity Rules

In Commander, a card's color identity determines which decks it can be included in. The color identity rules are:

1. A card's color identity includes all colored mana symbols that appear:

   • In its mana cost
   • In its rules text
   • On either face of a double-faced card
   • On all parts of a split or adventure card

2. Color identity is represented by the colors: White, Blue, Black, Red, and Green

3. A card's color identity can include colors even if the card itself is not those colors

4. Cards in a commander deck must only use colors within the color identity of the deck's commander

5. Basic lands with intrinsic mana abilities are only legal in decks where all their produced colors are in the commander's color identity

Component Implementation

#![allow(unused)]
fn main() {
/// Component representing a card's color identity
#[derive(Component, Debug, Clone, Reflect)]
pub struct ColorIdentity {
    /// White in color identity
    pub white: bool,
    /// Blue in color identity
    pub blue: bool,
    /// Black in color identity
    pub black: bool,
    /// Red in color identity
    pub red: bool,
    /// Green in color identity
    pub green: bool,
}

impl ColorIdentity {
    /// Creates a new color identity from a set of colors
    pub fn new(white: bool, blue: bool, black: bool, red: bool, green: bool) -> Self {
        Self {
            white,
            blue,
            black,
            red,
            green,
        }
    }
    
    /// Creates a colorless identity
    pub fn colorless() -> Self {
        Self::new(false, false, false, false, false)
    }
    
    /// Checks if this color identity contains another
    pub fn contains(&self, other: &ColorIdentity) -> bool {
        (!other.white || self.white) &&
        (!other.blue || self.blue) &&
        (!other.black || self.black) &&
        (!other.red || self.red) &&
        (!other.green || self.green)
    }
    
    /// Gets the colors as an array of booleans [W, U, B, R, G]
    pub fn as_array(&self) -> [bool; 5] {
        [self.white, self.blue, self.black, self.red, self.green]
    }
    
    /// Gets the number of colors in this identity
    pub fn color_count(&self) -> usize {
        self.as_array().iter().filter(|&&color| color).count()
    }
    
    /// Checks if this is a colorless identity
    pub fn is_colorless(&self) -> bool {
        self.color_count() == 0
    }
}
}

Calculating Color Identity

The system for calculating a card's color identity needs to analyze all text and symbols on the card:

#![allow(unused)]
fn main() {
/// Calculates a card's color identity from its various components
pub fn calculate_color_identity(
    mana_cost: &Mana,
    rules_text: &str,
    card_type: &CardTypes,
) -> ColorIdentity {
    let mut identity = ColorIdentity::colorless();
    
    // Check mana cost
    identity.white = identity.white || mana_cost.white > 0;
    identity.blue = identity.blue || mana_cost.blue > 0;
    identity.black = identity.black || mana_cost.black > 0;
    identity.red = identity.red || mana_cost.red > 0;
    identity.green = identity.green || mana_cost.green > 0;
    
    // Check rules text for mana symbols using regex
    let re = Regex::new(r"\{([WUBRG])/([WUBRG])\}|\{([WUBRG])\}").unwrap();
    for cap in re.captures_iter(rules_text) {
        if let Some(hybrid_1) = cap.get(1) {
            match hybrid_1.as_str() {
                "W" => identity.white = true,
                "U" => identity.blue = true,
                "B" => identity.black = true,
                "R" => identity.red = true,
                "G" => identity.green = true,
                _ => {}
            }
        }
        if let Some(hybrid_2) = cap.get(2) {
            match hybrid_2.as_str() {
                "W" => identity.white = true,
                "U" => identity.blue = true,
                "B" => identity.black = true,
                "R" => identity.red = true,
                "G" => identity.green = true,
                _ => {}
            }
        }
        if let Some(single) = cap.get(3) {
            match single.as_str() {
                "W" => identity.white = true,
                "U" => identity.blue = true,
                "B" => identity.black = true,
                "R" => identity.red = true,
                "G" => identity.green = true,
                _ => {}
            }
        }
    }
    
    // Check for color indicators
    if let Some(colors) = card_type.get_color_indicator() {
        for color in colors {
            match color {
                Color::White => identity.white = true,
                Color::Blue => identity.blue = true,
                Color::Black => identity.black = true,
                Color::Red => identity.red = true,
                Color::Green => identity.green = true,
                _ => {}
            }
        }
    }
    
    identity
}
}

Deck Validation

Deck validation ensures that all cards in a deck match the commander's color identity:

#![allow(unused)]
fn main() {
/// System to validate deck color identity during deck construction
pub fn validate_deck_color_identity(
    commanders: Query<(&Commander, &ColorIdentity)>,
    cards: Query<(Entity, &InDeck, &ColorIdentity)>,
    mut validation_events: EventWriter<DeckValidationEvent>,
) {
    // For each deck
    let decks = cards.iter()
        .map(|(_, in_deck, _)| in_deck.deck)
        .collect::<HashSet<_>>();
    
    for deck in decks {
        // Find the commander(s) for this deck
        let deck_commanders = commanders.iter()
            .filter(|(cmdr, _)| cmdr.deck == deck)
            .collect::<Vec<_>>();
        
        if deck_commanders.is_empty() {
            validation_events.send(DeckValidationEvent::Invalid {
                deck,
                reason: "No commander found for deck".to_string(),
            });
            continue;
        }
        
        // Calculate the combined color identity for all commanders (for partner support)
        let mut combined_identity = ColorIdentity::colorless();
        for (_, identity) in deck_commanders.iter() {
            combined_identity.white |= identity.white;
            combined_identity.blue |= identity.blue;
            combined_identity.black |= identity.black;
            combined_identity.red |= identity.red;
            combined_identity.green |= identity.green;
        }
        
        // Check that all cards match the commander's color identity
        for (entity, in_deck, card_identity) in cards.iter() {
            if in_deck.deck != deck {
                continue;
            }
            
            if !combined_identity.contains(card_identity) {
                validation_events.send(DeckValidationEvent::InvalidCard {
                    deck,
                    card: entity,
                    reason: format!("Card color identity outside of commander's color identity"),
                });
            }
        }
    }
}
}

Special Cases

Partner Commanders

When using partner commanders, the deck's color identity is the union of both commanders' color identities:

#![allow(unused)]
fn main() {
/// System to handle partner commanders' combined color identity
pub fn handle_partner_color_identity(
    partners: Query<(Entity, &Partner, &ColorIdentity)>,
    decks: Query<&Deck>,
) {
    // Group partners by deck
    let mut deck_partners = HashMap::new();
    for (entity, partner, identity) in partners.iter() {
        deck_partners.entry(partner.deck)
            .or_insert_with(Vec::new)
            .push((entity, identity));
    }
    
    // For each deck with partners
    for (deck_entity, partners) in deck_partners.iter() {
        if let Ok(deck) = decks.get(*deck_entity) {
            // Calculate combined identity
            let mut combined = ColorIdentity::colorless();
            for (_, identity) in partners.iter() {
                combined.white |= identity.white;
                combined.blue |= identity.blue;
                combined.black |= identity.black;
                combined.red |= identity.red;
                combined.green |= identity.green;
            }
            
            // Store combined identity for deck validation
            // ...
        }
    }
}
}

Five-Color Commanders

Five-color commanders like "The Ur-Dragon" allow any card in the deck:

#![allow(unused)]
fn main() {
impl ColorIdentity {
    /// Checks if this is a five-color identity
    pub fn is_five_color(&self) -> bool {
        self.white && self.blue && self.black && self.red && self.green
    }
}
}

UI Representation

Color identity is visually represented in the UI:

1. The commander's color identity is displayed in the command zone
2. During deck construction, cards that don't match the commander's color identity are highlighted
3. Card browser filters can be set to only show cards matching the commander's color identity
4. Color identity is shown as colored pips in card displays

Testing

Example Tests

#![allow(unused)]
fn main() {
#[test]
fn test_color_identity_calculation() {
    // Test basic mana cost identity
    let cost = Mana::new(0, 1, 1, 0, 0, 0); // WU
    let identity = calculate_color_identity(&cost, "", &CardTypes::default());
    assert!(identity.white);
    assert!(identity.blue);
    assert!(!identity.black);
    assert!(!identity.red);
    assert!(!identity.green);
    
    // Test rules text identity
    let cost = Mana::new(0, 0, 0, 0, 0, 0); // Colorless
    let text = "Add {R} or {G} to your mana pool.";
    let identity = calculate_color_identity(&cost, text, &CardTypes::default());
    assert!(!identity.white);
    assert!(!identity.blue);
    assert!(!identity.black);
    assert!(identity.red);
    assert!(identity.green);
    
    // Test hybrid mana
    let cost = Mana::new(0, 0, 0, 0, 0, 0); // Colorless
    let text = "This spell costs {W/B} less to cast.";
    let identity = calculate_color_identity(&cost, text, &CardTypes::default());
    assert!(identity.white);
    assert!(!identity.blue);
    assert!(identity.black);
    assert!(!identity.red);
    assert!(!identity.green);
}

#[test]
fn test_deck_validation() {
    // Set up a test environment
    let mut app = App::new();
    app.add_systems(Update, validate_deck_color_identity)
        .add_event::<DeckValidationEvent>();
    
    // Create a Simic (Green-Blue) commander
    let commander_entity = app.world.spawn((
        Commander { deck: Entity::from_raw(1), ..Default::default() },
        ColorIdentity::new(false, true, false, false, true), // Blue-Green
    )).id();
    
    // Create a deck with the commander and some cards
    let deck_entity = Entity::from_raw(1);
    
    // Valid cards
    let valid_card1 = app.world.spawn((
        InDeck { deck: deck_entity },
        ColorIdentity::new(false, true, false, false, false), // Blue only
    )).id();
    
    let valid_card2 = app.world.spawn((
        InDeck { deck: deck_entity },
        ColorIdentity::new(false, false, false, false, true), // Green only
    )).id();
    
    // Invalid card (contains red)
    let invalid_card = app.world.spawn((
        InDeck { deck: deck_entity },
        ColorIdentity::new(false, true, false, true, true), // Blue-Red-Green
    )).id();
    
    // Run validation
    app.update();
    
    // Check validation results
    let events = app.world.resource::<Events<DeckValidationEvent>>();
    let mut reader = events.get_reader();
    
    let mut invalid_cards = Vec::new();
    for event in reader.read(&events) {
        if let DeckValidationEvent::InvalidCard { card, .. } = event {
            invalid_cards.push(*card);
        }
    }
    
    assert_eq!(invalid_cards.len(), 1);
    assert_eq!(invalid_cards[0], invalid_card);
}
}

Summary

Color identity in Commander is implemented as a comprehensive system that:

1. Correctly calculates color identity from all relevant card components
2. Enforces deck construction rules based on the commander's color identity
3. Supports special cases like partner commanders and colorless commanders
4. Provides clear visual feedback in the UI
5. Is thoroughly tested with both unit and integration tests

Commander-Specific Zone Mechanics

Overview

This section covers the implementation of Commander-specific zone mechanics in the Rummage game engine. For core zone mechanics that apply to all formats, see the MTG Core Zones documentation.

Commander Zone Extensions

Commander extends the basic MTG zone system by:

1. Adding the Command Zone - A special zone where commanders begin the game
2. Modifying Zone Transition Rules - Commanders can optionally move to the command zone instead of other zones
3. Introducing Commander Tax - Additional mana cost for casting commanders from the command zone

Contents

• Command Zone - Implementation of the command zone and commander-specific mechanics
• Zone Transitions - Special rules for commander movement between zones
• Zone Management - Extended zone implementation for Commander games

Key Commander Zone Mechanics

• Commander Placement: Commanders start in the command zone before the game begins
• Zone Replacement: When a commander would be put into a library, hand, graveyard, or exile, its owner may choose to put it into the command zone instead
• Commander Tax: Each time a commander is cast from the command zone, it costs an additional {2} for each previous time it has been cast from the command zone
• Partner Commanders: Special handling for decks with two commanders (Partner mechanic)
• Commander Backgrounds: Implementation of the Background mechanic for certain commanders

These Commander-specific zone mechanics build upon the core zone system to enable the unique gameplay experience of the Commander format.

Next: Command Zone

Command Zone Management

Overview

The Command Zone is a unique game zone central to the Commander format. This module manages the Command Zone, Commander card movement between zones, and the special rules surrounding Commander cards. It integrates with the zone management and player systems to provide a complete implementation of Commander-specific mechanics according to the official Magic: The Gathering Comprehensive Rules section 903.

Core Components

Command Zone Structure

#![allow(unused)]
fn main() {
#[derive(Resource)]
pub struct CommandZoneManager {
    // Maps player entity to their commander entities in the command zone
    pub command_zones: HashMap<Entity, Vec<Entity>>,
    
    // Tracks whether commanders are in the command zone or elsewhere
    pub commander_zone_status: HashMap<Entity, CommanderZoneLocation>,
    
    // Tracks the number of times each commander has been cast from the command zone
    pub cast_count: HashMap<Entity, u32>,
    
    // Tracks commanders that died/were exiled this turn (for state-based actions)
    pub died_this_turn: HashSet<Entity>,
    pub exiled_this_turn: HashSet<Entity>,
    
    // Track partner commanders and backgrounds
    pub commander_partnerships: HashMap<Entity, Entity>,
    pub backgrounds: HashMap<Entity, Entity>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CommanderZoneLocation {
    CommandZone,
    Battlefield,
    Graveyard,
    Exile,
    Library,
    Hand,
    Stack,
    Limbo, // Transitional state
}
}

Commander Components

#![allow(unused)]
fn main() {
#[derive(Component)]
pub struct Commander {
    pub owner: Entity,
    pub partner: Option<Entity>,
    pub background: Option<Entity>,
    pub color_identity: ColorIdentity,
}

#[derive(Component)]
pub struct CommanderCastable {
    pub base_cost: ManaCost,
    pub current_tax: u32,
}
}

Key Systems

Command Zone Initialization

#![allow(unused)]
fn main() {
pub fn initialize_command_zone(
    mut commands: Commands,
    mut command_zone: ResMut<CommandZoneManager>,
    players: Query<Entity, With<Player>>,
    commanders: Query<(Entity, &Commander)>,
) {
    // Create empty command zone entries for each player
    for player in players.iter() {
        command_zone.command_zones.insert(player, Vec::new());
    }
    
    // Place all commanders in their owners' command zones
    for (entity, commander) in commanders.iter() {
        if let Some(zone_list) = command_zone.command_zones.get_mut(&commander.owner) {
            zone_list.push(entity);
        }
        
        // Set initial zone status
        command_zone.commander_zone_status.insert(entity, CommanderZoneLocation::CommandZone);
        
        // Initialize cast count for commander tax
        command_zone.cast_count.insert(entity, 0);
        
        // Add castable component with initial tax of zero
        if let Ok(card) = commanders.get_component::<Card>(entity) {
            commands.entity(entity).insert(CommanderCastable {
                base_cost: card.cost.clone(),
                current_tax: 0,
            });
        }
    }
    
    // Set up partner relationships
    for (entity, commander) in commanders.iter() {
        if let Some(partner) = commander.partner {
            command_zone.commander_partnerships.insert(entity, partner);
        }
        
        if let Some(background) = commander.background {
            command_zone.backgrounds.insert(entity, background);
        }
    }
}
}

Commander Casting System

#![allow(unused)]
fn main() {
pub fn handle_commander_cast(
    mut commands: Commands,
    mut command_zone: ResMut<CommandZoneManager>,
    mut cast_events: EventReader<CastFromCommandZoneEvent>,
    mut castable: Query<&mut CommanderCastable>,
) {
    for event in cast_events.read() {
        let commander_entity = event.commander;
        
        // Update zone status
        command_zone.commander_zone_status.insert(commander_entity, CommanderZoneLocation::Stack);
        
        // Increment cast count for commander tax
        if let Some(count) = command_zone.cast_count.get_mut(&commander_entity) {
            *count += 1;
            
            // Update tax amount for next cast
            if let Ok(mut commander_castable) = castable.get_mut(commander_entity) {
                commander_castable.current_tax = *count * 2; // 2 mana per previous cast
            }
        }
        
        // Remove from command zone list
        if let Some(player_zone) = command_zone.command_zones.get_mut(&event.player) {
            if let Some(pos) = player_zone.iter().position(|&c| c == commander_entity) {
                player_zone.swap_remove(pos);
            }
        }
    }
}
}

Zone Transition Handler

#![allow(unused)]
fn main() {
pub fn handle_commander_zone_transitions(
    mut commands: Commands,
    mut command_zone: ResMut<CommandZoneManager>,
    mut zone_events: EventReader<ZoneTransitionEvent>,
    mut choice_events: EventWriter<CommanderZoneChoiceEvent>,
) {
    for event in zone_events.read() {
        // Only process events for commander entities
        if !command_zone.commander_zone_status.contains_key(&event.entity) {
            continue;
        }
        
        let destination = match event.destination {
            Zone::Graveyard => CommanderZoneLocation::Graveyard,
            Zone::Exile => CommanderZoneLocation::Exile,
            Zone::Library => CommanderZoneLocation::Library,
            Zone::Hand => CommanderZoneLocation::Hand,
            Zone::Battlefield => CommanderZoneLocation::Battlefield,
            Zone::Stack => CommanderZoneLocation::Stack,
            // Handle other zones...
            _ => continue,
        };
        
        // Record death/exile for state-based actions
        if destination == CommanderZoneLocation::Graveyard {
            command_zone.died_this_turn.insert(event.entity);
        } else if destination == CommanderZoneLocation::Exile {
            command_zone.exiled_this_turn.insert(event.entity);
        }
        
        // Update commander location
        command_zone.commander_zone_status.insert(event.entity, destination);
        
        // If moving to graveyard, exile, library, or hand, offer replacement to command zone
        if matches!(destination, 
            CommanderZoneLocation::Graveyard | 
            CommanderZoneLocation::Exile | 
            CommanderZoneLocation::Library | 
            CommanderZoneLocation::Hand) 
        {
            // Find owner
            let owner = commanders.get_component::<Commander>(event.entity)
                .map(|c| c.owner)
                .unwrap_or(event.controller);
                
            // Send choice event to owner
            choice_events.send(CommanderZoneChoiceEvent {
                commander: event.entity,
                owner,
                from_zone: destination,
            });
        }
    }
}
}

Command Zone API

The Command Zone module provides a public API for other modules to interact with commander-specific functionality:

#![allow(unused)]
fn main() {
impl CommandZoneManager {
    // Get the current tax for a commander
    pub fn get_commander_tax(&self, commander: Entity) -> u32 {
        self.cast_count.get(&commander).copied().unwrap_or(0) * 2
    }
    
    // Check if an entity is a commander
    pub fn is_commander(&self, entity: Entity) -> bool {
        self.commander_zone_status.contains_key(&entity)
    }
    
    // Move a commander to the command zone
    pub fn move_to_command_zone(&mut self, commander: Entity, owner: Entity) {
        // Update status
        self.commander_zone_status.insert(commander, CommanderZoneLocation::CommandZone);
        
        // Add to command zone list
        if let Some(zone) = self.command_zones.get_mut(&owner) {
            if !zone.contains(&commander) {
                zone.push(commander);
            }
        }
    }
    
    // Get all commanders for a player
    pub fn get_player_commanders(&self, player: Entity) -> Vec<Entity> {
        self.command_zones.get(&player)
            .cloned()
            .unwrap_or_default()
    }
}
}

The Command Zone management module is central to the Commander format, as it implements the unique rules that define the format, including the command zone, commander casting with tax, and zone transition replacements.

Commander Exile Zone

This section documents the implementation of the Exile Zone in the Commander format.

Overview

The Exile Zone in Magic: The Gathering represents a special area where cards are removed from the game. In Commander, there are specific interactions between the Exile Zone and the Command Zone that merit special attention.

Implementation Details

Exile Zone Component

#![allow(unused)]
fn main() {
#[derive(Component)]
pub struct ExileZone {
    pub contents: Vec<Entity>,
}
}

Commander-Specific Exile Interactions

When a commander would be exiled, the owner can choose to move it to the Command Zone instead. This is implemented through a player choice event:

#![allow(unused)]
fn main() {
fn handle_commander_exile(
    mut commands: Commands,
    mut exile_events: EventReader<ExileEvent>,
    commanders: Query<(Entity, &Commander)>,
    mut choice_events: EventWriter<PlayerChoiceEvent>,
) {
    for event in exile_events.iter() {
        if let Ok((entity, commander)) = commanders.get(event.card) {
            // Give player the choice to move to command zone instead
            choice_events.send(PlayerChoiceEvent {
                player: commander.owner,
                choices: vec![
                    PlayerChoice::MoveToExile,
                    PlayerChoice::MoveToCommandZone,
                ],
                context: ChoiceContext::CommanderExile { commander: entity },
            });
        }
    }
}
}

Exile-Based Effects

Many Commander cards interact with the Exile Zone in specific ways:

1. Temporary Exile: Effects that exile cards until certain conditions are met
2. Exile as Resource: Effects that use exiled cards for special abilities
3. Commander Reprocessing: When commanders return from exile, they reset any temporary effects

Testing

The Exile Zone implementation is tested with these scenarios:

#![allow(unused)]
fn main() {
#[test]
fn test_commander_exile_choice() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(CommanderPlugin);
    
    // Create test entities
    let player = app.world.spawn_empty().id();
    let commander = app.world.spawn((
        Commander { owner: player, cast_count: 0 },
        Card::default(),
    )).id();
    
    // Trigger exile event
    app.world.resource_mut::<Events<ExileEvent>>().send(ExileEvent {
        card: commander,
        source: None,
    });
    
    // Run systems
    app.update();
    
    // Verify player received choice
    let choices = app.world.resource::<Events<PlayerChoiceEvent>>()
        .get_reader()
        .iter(app.world.resource::<Events<PlayerChoiceEvent>>())
        .collect::<Vec<_>>();
    
    assert!(!choices.is_empty());
    // Additional assertions...
}
}

Integration with Other Zones

The Exile Zone interacts with other zones in specific ways:

• Command Zone: Commander replacement effect
• Battlefield: "Until end of turn" exile effects
• Graveyard: "Exile from graveyard" effects common in Commander

Next Steps

• Command Zone
• Zone Transitions

This page is part of the Game Zones documentation for the Commander format.

Commander Zone Transitions

Overview

Zone transitions are a critical aspect of the Commander format, particularly with the special replacement effect that allows commanders to return to the Command Zone instead of going to certain other zones. This document details the implementation of these zone transition rules according to Magic: The Gathering Comprehensive Rules section 903.9.

Commander Zone Transition Rules

According to the rules:

1. If a commander would be exiled or put into a hand, graveyard, or library from anywhere, its owner may choose to put it into the command zone instead. This is a replacement effect.
2. The choice is made as the zone change would occur.
3. If a commander is moved directly to the command zone in this way, its last known information is used to determine what happened to it.

Implementation Components

Zone Transition Events

#![allow(unused)]
fn main() {
#[derive(Event)]
pub struct ZoneTransitionEvent {
    pub entity: Entity,
    pub controller: Entity,
    pub source: Zone,
    pub destination: Zone,
    pub reason: ZoneChangeReason,
}

#[derive(Event)]
pub struct CommanderZoneChoiceEvent {
    pub commander: Entity,
    pub owner: Entity,
    pub from_zone: CommanderZoneLocation,
}

#[derive(Event)]
pub struct CommanderZoneChoiceResponseEvent {
    pub commander: Entity,
    pub owner: Entity,
    pub choose_command_zone: bool,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ZoneChangeReason {
    Cast,
    Resolve,
    PutOntoBattlefield,
    Destroy,
    Sacrifice,
    Exile,
    ReturnToHand,
    PutIntoGraveyard,
    PutIntoLibrary,
    PhasingOut,
    PhasingIn,
    StateBasedAction,
    Replacement,
    Other,
}
}

Zone Transition System

#![allow(unused)]
fn main() {
pub fn handle_commander_zone_choice_responses(
    mut commands: Commands,
    mut command_zone: ResMut<CommandZoneManager>,
    mut response_events: EventReader<CommanderZoneChoiceResponseEvent>,
    mut state_actions: EventWriter<StateBasedActionEvent>,
) {
    for event in response_events.read() {
        if event.choose_command_zone {
            // Update commander location to Command Zone
            command_zone.commander_zone_status.insert(event.commander, CommanderZoneLocation::CommandZone);
            
            // Add to command zone list if not already there
            if let Some(zone) = command_zone.command_zones.get_mut(&event.owner) {
                if !zone.contains(&event.commander) {
                    zone.push(event.commander);
                }
            }
            
            // Trigger any state-based actions that might care about this
            state_actions.send(StateBasedActionEvent::CommanderZoneChanged(event.commander));
        }
    }
}
}

Zone Transition Logic

The zone transition system follows this logical flow:

1. A card is about to change zones (triggered by a game event)
2. The system checks if the card is a commander
3. If it is, and the destination is hand, graveyard, library, or exile: a. A choice event is sent to the owner b. The game may need to wait for user input (or AI decision) c. The owner chooses whether to redirect to command zone
4. Based on the choice, the card either goes to the original destination or the command zone
5. State-based actions are triggered to handle any consequences

Zone Transition Diagram

                   +-----------------+
                   | Zone Change     |
                   | Triggered       |
                   +--------+--------+
                            |
                   +--------v--------+
                   | Is it a         |
              No   | Commander?      |   Yes
          +--------+                 +--------+
          |        +-----------------+        |
          |                                   |
+---------v---------+               +---------v---------+
| Normal Zone       |               | Destination GY,   |   No
| Change Processing |               | Hand, Library,    +--------+
+-------------------+               | or Exile?         |        |
                                    +---------+---------+        |
                                              |                  |
                                              | Yes              |
                                    +---------v---------+  +-----v------+
                                    | Send Choice Event |  | Normal Zone|
                                    | to Owner          |  | Change     |
                                    +---------+---------+  +------------+
                                              |
                             +-----------+    |    +------------+
                             |           |    |    |            |
                      +------v------+    |    |  +-v-----------v--+
                      | Choose      |    |    |  | Choose Original |
                      | Command Zone|<---+----+->| Destination     |
                      +------+------+         |  +--------+--------+
                             |                |           |
               +-------------v-------------+  |  +--------v---------+
               | Move to Command Zone      |  |  | Move to Original |
               | Update Status             |  |  | Destination      |
               | Trigger State-Based       |  |  | Update Status    |
               | Actions                   |  |  | Trigger Effects  |
               +---------------------------+  |  +------------------+
                                              |
                                              v
                                    +-------------------+
                                    | Continue Game     |
                                    | Processing        |
                                    +-------------------+

Special Cases

Death Triggers

When a commander would die (go to the graveyard from the battlefield), it can create complications with death triggers:

#![allow(unused)]
fn main() {
pub fn handle_commander_death_triggers(
    command_zone: Res<CommandZoneManager>,
    mut death_events: EventReader<DeathEvent>,
    mut death_triggers: EventWriter<TriggerEvent>,
) {
    for event in death_events.read() {
        let entity = event.entity;
        
        // Check if this is a commander that was redirected to the command zone
        if command_zone.is_commander(entity) && 
           command_zone.commander_zone_status.get(&entity) == Some(&CommanderZoneLocation::CommandZone) &&
           command_zone.died_this_turn.contains(&entity) {
            
            // Create death trigger events even though it went to command zone
            death_triggers.send(TriggerEvent::Death {
                entity,
                from_battlefield: true,
                redirected_to_command_zone: true,
            });
        }
    }
}
}

Multiple Zone Changes

If a commander would quickly change zones multiple times, each transition is handled separately:

#![allow(unused)]
fn main() {
pub fn handle_rapid_zone_changes(
    mut command_zone: ResMut<CommandZoneManager>,
    mut transition_events: EventReader<ZoneTransitionEvent>,
    mut choice_events: EventWriter<CommanderZoneChoiceEvent>,
) {
    // Track entities that have already had a choice offered this update
    let mut already_processed = HashSet::new();
    
    for event in transition_events.read() {
        // Skip non-commander entities
        if !command_zone.is_commander(event.entity) {
            continue;
        }
        
        // Skip if we already processed this entity this frame
        if already_processed.contains(&event.entity) {
            continue;
        }
        
        // Process as normal...
        
        // Mark as processed
        already_processed.insert(event.entity);
    }
}
}

The zone transition system is one of the most complex parts of the Commander implementation, as it needs to handle the unique replacement effects that define the format while preserving proper triggers and game state.

Zone Management in Commander

Overview

Zone management in Commander follows the standard Magic: The Gathering zone structure but with special considerations for the Command Zone and commander-specific zone transitions. This document covers the implementation of zone management in the Commander format.

Game Zones

Commander uses all standard Magic: The Gathering zones plus the Command Zone:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Zone {
    Battlefield,
    Stack,
    Hand,
    Library,
    Graveyard,
    Exile,
    Command,
    Limbo, // Transitional zone
}
}

Zone Manager Implementation

The Zone Manager keeps track of all entities in each zone:

#![allow(unused)]
fn main() {
#[derive(Resource)]
pub struct ZoneManager {
    // Maps zone type to a set of entities in that zone
    pub zones: HashMap<Zone, HashSet<Entity>>,
    
    // Maps entity to its current zone
    pub entity_zones: HashMap<Entity, Zone>,
    
    // Maps player to their personal zones (hand, library, etc.)
    pub player_zones: HashMap<Entity, HashMap<Zone, HashSet<Entity>>>,
}
}

Key Systems

Zone Initialization

#![allow(unused)]
fn main() {
pub fn initialize_zones(
    mut commands: Commands,
    mut zone_manager: ResMut<ZoneManager>,
    players: Query<Entity, With<Player>>,
) {
    // Initialize global zones
    zone_manager.zones.insert(Zone::Battlefield, HashSet::new());
    zone_manager.zones.insert(Zone::Stack, HashSet::new());
    zone_manager.zones.insert(Zone::Exile, HashSet::new());
    zone_manager.zones.insert(Zone::Command, HashSet::new());
    zone_manager.zones.insert(Zone::Limbo, HashSet::new());
    
    // Initialize player-specific zones
    for player in players.iter() {
        let mut player_zones = HashMap::new();
        player_zones.insert(Zone::Hand, HashSet::new());
        player_zones.insert(Zone::Library, HashSet::new());
        player_zones.insert(Zone::Graveyard, HashSet::new());
        
        zone_manager.player_zones.insert(player, player_zones);
    }
}
}

Zone Transition System

#![allow(unused)]
fn main() {
pub fn handle_zone_transitions(
    mut commands: Commands,
    mut zone_manager: ResMut<ZoneManager>,
    mut events: EventReader<ZoneTransitionEvent>,
    mut commander_events: EventWriter<CommanderZoneTransitionEvent>,
    command_zone: Res<CommandZoneManager>,
) {
    for event in events.read() {
        let entity = event.entity;
        let controller = event.controller;
        let source = event.source;
        let destination = event.destination;
        
        // Check if entity is a commander for special handling
        let is_commander = command_zone.is_commander(entity);
        
        // Special case for commander - emit commander-specific event
        if is_commander {
            commander_events.send(CommanderZoneTransitionEvent {
                commander: entity,
                controller,
                source,
                destination,
                reason: event.reason,
            });
            
            // Let the commander system handle it
            continue;
        }
        
        // Normal zone transition handling
        handle_normal_zone_transition(
            &mut zone_manager, 
            entity, 
            controller, 
            source, 
            destination
        );
    }
}

fn handle_normal_zone_transition(
    zone_manager: &mut ZoneManager,
    entity: Entity,
    controller: Entity,
    source: Zone,
    destination: Zone,
) {
    // Remove from source zone
    match source {
        Zone::Battlefield | Zone::Stack | Zone::Exile | Zone::Command | Zone::Limbo => {
            if let Some(zone_entities) = zone_manager.zones.get_mut(&source) {
                zone_entities.remove(&entity);
            }
        },
        Zone::Hand | Zone::Library | Zone::Graveyard => {
            if let Some(player_zones) = zone_manager.player_zones.get_mut(&controller) {
                if let Some(zone_entities) = player_zones.get_mut(&source) {
                    zone_entities.remove(&entity);
                }
            }
        }
    }
    
    // Add to destination zone
    match destination {
        Zone::Battlefield | Zone::Stack | Zone::Exile | Zone::Command | Zone::Limbo => {
            if let Some(zone_entities) = zone_manager.zones.get_mut(&destination) {
                zone_entities.insert(entity);
            }
        },
        Zone::Hand | Zone::Library | Zone::Graveyard => {
            if let Some(player_zones) = zone_manager.player_zones.get_mut(&controller) {
                if let Some(zone_entities) = player_zones.get_mut(&destination) {
                    zone_entities.insert(entity);
                }
            }
        }
    }
    
    // Update entity's current zone
    zone_manager.entity_zones.insert(entity, destination);
}
}

Command Zone Integration

The Zone Manager integrates with the Command Zone manager to handle special Commander-specific zone transitions:

#![allow(unused)]
fn main() {
pub fn sync_command_zone(
    mut zone_manager: ResMut<ZoneManager>,
    command_zone: Res<CommandZoneManager>,
) {
    // Get all entities currently in the command zone
    let mut command_zone_entities = HashSet::new();
    
    for player_commanders in command_zone.command_zones.values() {
        for commander in player_commanders.iter() {
            command_zone_entities.insert(*commander);
        }
    }
    
    // Update the zone manager's command zone
    if let Some(zone_entities) = zone_manager.zones.get_mut(&Zone::Command) {
        *zone_entities = command_zone_entities;
    }
    
    // Update entity_zones for all commanders
    for (commander, location) in command_zone.commander_zone_status.iter() {
        if *location == CommanderZoneLocation::CommandZone {
            zone_manager.entity_zones.insert(*commander, Zone::Command);
        }
    }
}
}

Special Commander Zone Considerations

Casting From Command Zone

#![allow(unused)]
fn main() {
pub fn enable_command_zone_casting(
    mut commands: Commands,
    zone_manager: Res<ZoneManager>,
    command_zone: Res<CommandZoneManager>,
    mut players: Query<(Entity, &mut PlayerActions)>,
) {
    for (player, mut actions) in players.iter_mut() {
        // Get player's commanders in the command zone
        let commanders = command_zone
            .command_zones
            .get(&player)
            .cloned()
            .unwrap_or_default();
        
        // Add castable action for each commander
        for commander in commanders {
            if let Some(tax) = command_zone.cast_count.get(&commander) {
                actions.castable_from_command_zone.insert(
                    commander, 
                    *tax * 2 // 2 mana per previous cast
                );
            }
        }
    }
}
}

Zone Visibility

Zone visibility in Commander follows standard MTG rules with players only seeing their own hands and libraries:

#![allow(unused)]
fn main() {
pub fn update_zone_visibility(
    mut commands: Commands,
    zone_manager: Res<ZoneManager>,
    players: Query<Entity, With<Player>>,
) {
    for player in players.iter() {
        // Add components for visible zones
        let mut visible_entities = HashSet::new();
        
        // Public zones (visible to all)
        for zone in [Zone::Battlefield, Zone::Stack, Zone::Exile, Zone::Command].iter() {
            if let Some(zone_entities) = zone_manager.zones.get(zone) {
                visible_entities.extend(zone_entities.iter());
            }
        }
        
        // All players' graveyards are public
        for (other_player, zones) in zone_manager.player_zones.iter() {
            if let Some(graveyard) = zones.get(&Zone::Graveyard) {
                visible_entities.extend(graveyard.iter());
            }
        }
        
        // Player's own hand and library (top card only if revealed)
        if let Some(player_zones) = zone_manager.player_zones.get(&player) {
            if let Some(hand) = player_zones.get(&Zone::Hand) {
                visible_entities.extend(hand.iter());
            }
            
            // Other private zone logic...
        }
        
        // Update visibility components
        commands.entity(player).insert(ZoneVisibility {
            visible_entities: visible_entities.into_iter().collect(),
        });
    }
}
}

The Zone Management system provides a complete implementation of Magic: The Gathering zones with special handling for Commander-specific mechanics, particularly related to the Command Zone and commander movement between zones.

Zone Tests

This section contains tests related to the various zone mechanics in the Commander format.

Command Zone Tests

The Command Zone Tests verify the proper behavior of the Command Zone and related mechanics, such as:

• Commander movement to and from the command zone
• Commander tax calculation
• Proper tracking of command zone events
• Integration with state-based actions

These tests ensure that the unique Commander zone mechanics function correctly within the game engine.

Command Zone Tests

Overview

This document outlines test cases for the Command Zone in the Commander format. These tests ensure correct implementation of all Commander-specific rules related to the Command Zone, commander casting, commander tax, and zone transitions.

Test Case: Commander Casting

Test: Initial Commander Cast from Command Zone

#![allow(unused)]
fn main() {
#[test]
fn test_initial_commander_cast() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (check_commander_cast, update_command_zone));
       
    // Create player and their commander
    let player = app.world.spawn((
        Player {},
        Mana::default(),
        ActivePlayer,
    )).id();
    
    let commander = app.world.spawn((
        Card { 
            name: "Test Commander".to_string(),
            cost: ManaCost::from_string("{2}{G}{G}").unwrap(),
        },
        Commander { owner: player, cast_count: 0 },
        Zone::CommandZone,
    )).id();
    
    // Player has enough mana to cast
    let mut player_mana = app.world.get_mut::<Mana>(player).unwrap();
    player_mana.add(ManaType::Green, 2);
    player_mana.add(ManaType::Colorless, 2);
    
    // Attempt to cast commander
    app.world.send_event(CastSpellEvent {
        caster: player,
        card: commander,
    });
    app.update();
    
    // Verify commander moved to stack
    assert_eq!(app.world.get::<Zone>(commander).unwrap(), &Zone::Stack);
    
    // Verify no additional tax was applied (first cast)
    assert_eq!(app.world.get::<Commander>(commander).unwrap().cast_count, 1);
}
}

Test: Recasting Commander with Commander Tax

#![allow(unused)]
fn main() {
#[test]
fn test_commander_tax() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (check_commander_cast, update_command_zone, apply_commander_tax));
       
    // Create player and their commander
    let player = app.world.spawn((
        Player {},
        Mana::default(),
        ActivePlayer,
    )).id();
    
    let commander = app.world.spawn((
        Card { 
            name: "Test Commander".to_string(),
            cost: ManaCost::from_string("{2}{G}{G}").unwrap(),
        },
        Commander { owner: player, cast_count: 1 }, // Already cast once before
        Zone::CommandZone,
    )).id();
    
    // Player has enough mana to cast with tax
    let mut player_mana = app.world.get_mut::<Mana>(player).unwrap();
    player_mana.add(ManaType::Green, 2);
    player_mana.add(ManaType::Colorless, 4);  // 2 original + 2 tax
    
    // Attempt to cast commander
    app.world.send_event(CastSpellEvent {
        caster: player,
        card: commander,
    });
    app.update();
    
    // Verify commander moved to stack
    assert_eq!(app.world.get::<Zone>(commander).unwrap(), &Zone::Stack);
    
    // Verify cast count was incremented
    assert_eq!(app.world.get::<Commander>(commander).unwrap().cast_count, 2);
    
    // Verify mana was properly deducted including tax
    let player_mana = app.world.get::<Mana>(player).unwrap();
    assert_eq!(player_mana.get(ManaType::Green), 0);
    assert_eq!(player_mana.get(ManaType::Colorless), 0);
}
}

Test: Insufficient Mana for Commander Tax

#![allow(unused)]
fn main() {
#[test]
fn test_insufficient_mana_for_commander_tax() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (check_commander_cast, update_command_zone, apply_commander_tax));
       
    // Create player and their commander
    let player = app.world.spawn((
        Player {},
        Mana::default(),
        ActivePlayer,
    )).id();
    
    let commander = app.world.spawn((
        Card { 
            name: "Test Commander".to_string(),
            cost: ManaCost::from_string("{2}{G}{G}").unwrap(),
        },
        Commander { owner: player, cast_count: 2 }, // Already cast twice before
        Zone::CommandZone,
    )).id();
    
    // Player doesn't have enough mana for tax
    let mut player_mana = app.world.get_mut::<Mana>(player).unwrap();
    player_mana.add(ManaType::Green, 2);
    player_mana.add(ManaType::Colorless, 3);  // 2 original + 4 tax needed, only 3 available
    
    // Attempt to cast commander
    app.world.send_event(CastSpellEvent {
        caster: player,
        card: commander,
    });
    app.update();
    
    // Verify commander stayed in command zone
    assert_eq!(app.world.get::<Zone>(commander).unwrap(), &Zone::CommandZone);
    
    // Verify cast count was not incremented
    assert_eq!(app.world.get::<Commander>(commander).unwrap().cast_count, 2);
}
}

Test Case: Zone Transitions

Test: Commander Dies and Goes to Command Zone

#![allow(unused)]
fn main() {
#[test]
fn test_commander_death_to_command_zone() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (handle_zone_transitions, commander_replacement_effects));
       
    // Create player and their commander
    let player = app.world.spawn((
        Player {},
        CommanderZoneChoice { use_command_zone: true },
    )).id();
    
    let commander = app.world.spawn((
        Card { name: "Test Commander".to_string() },
        Commander { owner: player, cast_count: 1 },
        Zone::Battlefield,
    )).id();
    
    // Trigger death of commander
    app.world.send_event(ZoneChangeEvent {
        entity: commander,
        from: Zone::Battlefield,
        to: Zone::Graveyard,
        cause: ZoneChangeCause::Death,
    });
    app.update();
    
    // Verify commander went to command zone instead of graveyard
    assert_eq!(app.world.get::<Zone>(commander).unwrap(), &Zone::CommandZone);
}
}

Test: Commander Goes to Exile and Replaced to Command Zone

#![allow(unused)]
fn main() {
#[test]
fn test_commander_exile_to_command_zone() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (handle_zone_transitions, commander_replacement_effects));
       
    // Create player and their commander
    let player = app.world.spawn((
        Player {},
        CommanderZoneChoice { use_command_zone: true },
    )).id();
    
    let commander = app.world.spawn((
        Card { name: "Test Commander".to_string() },
        Commander { owner: player, cast_count: 1 },
        Zone::Battlefield,
    )).id();
    
    // Trigger exile of commander
    app.world.send_event(ZoneChangeEvent {
        entity: commander,
        from: Zone::Battlefield,
        to: Zone::Exile,
        cause: ZoneChangeCause::Exile,
    });
    app.update();
    
    // Verify commander went to command zone instead of exile
    assert_eq!(app.world.get::<Zone>(commander).unwrap(), &Zone::CommandZone);
}
}

Test: Commander Goes to Hand by Player Choice

#![allow(unused)]
fn main() {
#[test]
fn test_commander_to_hand_by_choice() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (handle_zone_transitions, commander_replacement_effects));
       
    // Create player and their commander
    let player = app.world.spawn((
        Player {},
        CommanderZoneChoice { use_command_zone: false }, // Choose not to use command zone
    )).id();
    
    let commander = app.world.spawn((
        Card { name: "Test Commander".to_string() },
        Commander { owner: player, cast_count: 1 },
        Zone::Battlefield,
    )).id();
    
    // Trigger bounce of commander
    app.world.send_event(ZoneChangeEvent {
        entity: commander,
        from: Zone::Battlefield,
        to: Zone::Hand,
        cause: ZoneChangeCause::ReturnToHand,
    });
    app.update();
    
    // Verify commander went to hand as chosen
    assert_eq!(app.world.get::<Zone>(commander).unwrap(), &Zone::Hand);
}
}

Test Case: Partner Commanders

Test: Two Partner Commanders in Command Zone

#![allow(unused)]
fn main() {
#[test]
fn test_partner_commanders() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (check_command_zone_validity, handle_partner_mechanics));
       
    // Create player
    let player = app.world.spawn((
        Player {},
        CommanderList::default(),
    )).id();
    
    // Create two partner commanders
    let commander1 = app.world.spawn((
        Card { name: "Partner Commander 1".to_string() },
        Commander { owner: player, cast_count: 0 },
        PartnerAbility,
        Zone::CommandZone,
    )).id();
    
    let commander2 = app.world.spawn((
        Card { name: "Partner Commander 2".to_string() },
        Commander { owner: player, cast_count: 0 },
        PartnerAbility,
        Zone::CommandZone,
    )).id();
    
    // Add commanders to player's commander list
    let mut commander_list = app.world.get_mut::<CommanderList>(player).unwrap();
    commander_list.add(commander1);
    commander_list.add(commander2);
    app.update();
    
    // Verify player can have two commanders because they have partner
    let validation_errors = app.world.resource::<ValidationErrors>();
    assert!(validation_errors.is_empty());
    
    // Verify both commanders are in the command zone
    assert_eq!(app.world.get::<Zone>(commander1).unwrap(), &Zone::CommandZone);
    assert_eq!(app.world.get::<Zone>(commander2).unwrap(), &Zone::CommandZone);
}
}

Test Case: Command Zone Visibility

Test: Command Zone Cards Visible to All Players

#![allow(unused)]
fn main() {
#[test]
fn test_command_zone_visibility() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, check_card_visibility);
       
    // Create multiple players
    let player1 = app.world.spawn(Player {}).id();
    let player2 = app.world.spawn(Player {}).id();
    let player3 = app.world.spawn(Player {}).id();
    
    // Create a commander in the command zone
    let commander = app.world.spawn((
        Card { name: "Test Commander".to_string() },
        Commander { owner: player1, cast_count: 0 },
        Zone::CommandZone,
        Visibility::default(),
    )).id();
    
    // Update visibility
    app.update();
    
    // Verify all players can see the commander in command zone
    let visibility = app.world.get::<Visibility>(commander).unwrap();
    assert!(visibility.is_visible_to(player1));
    assert!(visibility.is_visible_to(player2));
    assert!(visibility.is_visible_to(player3));
}
}

Test Case: Commander Identity Restrictions

Test: Card Color Identity Validation for Commander Deck

#![allow(unused)]
fn main() {
#[test]
fn test_color_identity_restrictions() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, validate_deck_color_identity);
       
    // Create player and commander
    let player = app.world.spawn(Player {}).id();
    
    let commander = app.world.spawn((
        Card { name: "Mono-Green Commander".to_string() },
        Commander { owner: player, cast_count: 0 },
        ColorIdentity { colors: vec![Color::Green] },
    )).id();
    
    // Create legal and illegal cards for the deck
    let legal_card = app.world.spawn((
        Card { name: "Green Card".to_string() },
        ColorIdentity { colors: vec![Color::Green] },
        InDeck { owner: player },
    )).id();
    
    let illegal_card = app.world.spawn((
        Card { name: "Blue Card".to_string() },
        ColorIdentity { colors: vec![Color::Blue] },
        InDeck { owner: player },
    )).id();
    
    // Create deck with the commander
    app.world.spawn((
        Deck { owner: player },
        CommanderDeck { commander: commander },
        Cards { entities: vec![legal_card, illegal_card] },
    ));
    
    // Validate deck
    app.update();
    
    // Verify validation errors for illegal card
    let validation_errors = app.world.resource::<ValidationErrors>();
    assert!(!validation_errors.is_empty());
    assert!(validation_errors.contains_error_about(illegal_card, "color identity"));
}
}

These test cases provide comprehensive coverage of the Command Zone mechanics and ensure that all the format-specific rules are correctly implemented and enforced.

Turns and Phases

This section covers the implementation of turn structure and phases in the Commander format.

Contents

• Turn Structure - Complete turn sequence implementation
• Phase Management - Handling of individual phases and steps
• Priority System - Priority passing within phases
• Extra Turns & Modifications - Extra turns and turn modification effects
• Multiplayer Turn Handling - Multiplayer-specific turn considerations

The turns and phases section defines how the turn structure of Commander games is implemented, with special consideration for multiplayer dynamics:

• Standard Magic turn structure (untap, upkeep, draw, main phases, combat, etc.)
• Multiplayer turn order determination and rotation
• Special handling for simultaneous player actions
• Turn-based effects in multiplayer contexts
• Turn modification effects (extra turns, skipped phases, etc.)

While the basic turn structure in Commander follows standard Magic rules, the multiplayer nature of the format introduces complexity in turn management, particularly around priority passing and simultaneous effects.

Turn Structure

Overview

The Turn Structure module manages the flow of a Commander game, handling the sequence of phases and steps within each player's turn. It coordinates player transitions, priority passing, and phase-specific actions while accounting for the multiplayer nature of Commander.

Core Turn Sequence

A turn in Commander follows the standard Magic: The Gathering sequence:

1. Beginning Phase

   • Untap Step
   • Upkeep Step
   • Draw Step

2. Precombat Main Phase

3. Combat Phase

   • Beginning of Combat Step
   • Declare Attackers Step
   • Declare Blockers Step
   • Combat Damage Step
   • End of Combat Step

4. Postcombat Main Phase

5. Ending Phase

   • End Step
   • Cleanup Step

Multiplayer Considerations

In Commander, turn order proceeds clockwise from the starting player. The format introduces special considerations:

• Turn Order Determination: Typically random at the start of the game
• Player Elimination: When a player loses, turns continue with the remaining players
• Extra Turns: Cards that grant extra turns work the same as in standard Magic
• "Skip your next turn" effects: These follow standard Magic rules but can have significant political impact

Data Structures

The turn structure is managed through the following robust data structures:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Phase {
    Beginning(BeginningStep),
    Precombat(PrecombatStep),
    Combat(CombatStep),
    Postcombat(PostcombatStep),
    Ending(EndingStep),
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum BeginningStep {
    Untap,
    Upkeep,
    Draw,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum PrecombatStep {
    Main,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum CombatStep {
    Beginning,
    DeclareAttackers,
    DeclareBlockers,
    FirstStrike,
    CombatDamage,
    End,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum PostcombatStep {
    Main,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum EndingStep {
    End,
    Cleanup,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ExtraTurnSource {
    Card(Entity),
    Ability(Entity, Entity), // (Source, Ability)
    Rule,
}

#[derive(Resource)]
pub struct TurnManager {
    // Current turn information
    pub current_phase: Phase,
    pub active_player_index: usize,
    pub turn_number: u32,
    
    // Priority system
    pub priority_player_index: usize,
    pub all_players_passed: bool,
    pub stack_is_empty: bool,
    
    // Multiplayer tracking
    pub player_order: Vec<Entity>,
    pub extra_turns: VecDeque<(Entity, ExtraTurnSource)>,
    pub skipped_turns: HashSet<Entity>,
    
    // Time tracking
    pub time_limits: HashMap<Entity, Duration>,
    pub turn_started_at: Option<Instant>,
    
    // Phase history for reverting game states and debugging
    pub phase_history: VecDeque<(Phase, Entity)>,
    
    // Special phase tracking
    pub additional_phases: VecDeque<(Phase, Entity)>,
    pub modified_phases: HashMap<Phase, PhaseModification>,
}

#[derive(Debug, Clone)]
pub struct PhaseModification {
    pub source: Entity,
    pub skip_priority: bool,
    pub skip_actions: bool,
    pub additional_actions: Vec<GameAction>,
}
}

Detailed Implementation

Phase Progression System

#![allow(unused)]
fn main() {
impl TurnManager {
    // Advances to the next phase in the turn sequence
    pub fn advance_phase(&mut self) -> Result<Phase, TurnError> {
        let previous_phase = self.current_phase;
        self.current_phase = match self.current_phase {
            Phase::Beginning(BeginningStep::Untap) => Phase::Beginning(BeginningStep::Upkeep),
            Phase::Beginning(BeginningStep::Upkeep) => Phase::Beginning(BeginningStep::Draw),
            Phase::Beginning(BeginningStep::Draw) => Phase::Precombat(PrecombatStep::Main),
            Phase::Precombat(PrecombatStep::Main) => Phase::Combat(CombatStep::Beginning),
            Phase::Combat(CombatStep::Beginning) => Phase::Combat(CombatStep::DeclareAttackers),
            Phase::Combat(CombatStep::DeclareAttackers) => Phase::Combat(CombatStep::DeclareBlockers),
            // Check if first strike damage should happen
            Phase::Combat(CombatStep::DeclareBlockers) => {
                if self.has_first_strike_creatures() {
                    Phase::Combat(CombatStep::FirstStrike)
                } else {
                    Phase::Combat(CombatStep::CombatDamage)
                }
            },
            Phase::Combat(CombatStep::FirstStrike) => Phase::Combat(CombatStep::CombatDamage),
            Phase::Combat(CombatStep::CombatDamage) => Phase::Combat(CombatStep::End),
            Phase::Combat(CombatStep::End) => Phase::Postcombat(PostcombatStep::Main),
            Phase::Postcombat(PostcombatStep::Main) => Phase::Ending(EndingStep::End),
            Phase::Ending(EndingStep::End) => Phase::Ending(EndingStep::Cleanup),
            Phase::Ending(EndingStep::Cleanup) => {
                // Check for additional or extra turns
                self.process_turn_end()?;
                // The next turn's first phase
                Phase::Beginning(BeginningStep::Untap)
            }
        };
        
        // Record phase change in history
        self.phase_history.push_back((previous_phase, self.get_active_player()));
        
        // Check if this phase should be modified or skipped
        if let Some(modification) = self.modified_phases.get(&self.current_phase) {
            if modification.skip_actions {
                // Skip this phase and move to the next one
                return self.advance_phase();
            }
        }
        
        // Handle priority assignment for the new phase
        self.reset_priority_for_new_phase();
        
        Ok(self.current_phase)
    }
    
    // Process the end of a turn
    fn process_turn_end(&mut self) -> Result<(), TurnError> {
        // Check if there are additional phases for this turn
        if let Some((phase, _)) = self.additional_phases.pop_front() {
            self.current_phase = phase;
            return Ok(());
        }
        
        // Move to the next player
        let next_player = self.determine_next_player()?;
        self.active_player_index = self.player_order.iter()
            .position(|&p| p == next_player)
            .ok_or(TurnError::InvalidPlayerIndex)?;
        self.turn_number += 1;
        
        // Reset turn timer
        self.turn_started_at = Some(Instant::now());
        
        Ok(())
    }
    
    // Determine who takes the next turn
    fn determine_next_player(&mut self) -> Result<Entity, TurnError> {
        // Check for extra turns first
        if let Some((player, source)) = self.extra_turns.pop_front() {
            // Log extra turn for game record
            info!("Player {:?} is taking an extra turn from source {:?}", player, source);
            return Ok(player);
        }
        
        // Get the next player in turn order
        let next_index = (self.active_player_index + 1) % self.player_order.len();
        let next_player = self.player_order[next_index];
        
        // Check if the next player should skip their turn
        if self.skipped_turns.remove(&next_player) {
            // Record the skipped turn
            info!("Player {:?} is skipping their turn", next_player);
            
            // Move to the player after that
            self.active_player_index = next_index;
            return self.determine_next_player();
        }
        
        Ok(next_player)
    }
}
}

Priority System

#![allow(unused)]
fn main() {
impl TurnManager {
    // Reset priority for a new phase
    fn reset_priority_for_new_phase(&mut self) {
        self.all_players_passed = false;
        
        // In most phases, active player gets priority first
        self.priority_player_index = self.active_player_index;
        
        // For Beginning::Untap and Ending::Cleanup, no player gets priority by default
        match self.current_phase {
            Phase::Beginning(BeginningStep::Untap) | Phase::Ending(EndingStep::Cleanup) => {
                self.all_players_passed = true;
            },
            _ => {}
        }
    }
    
    // Pass priority to the next player
    pub fn pass_priority(&mut self) -> Result<(), TurnError> {
        // Calculate next player with priority
        let next_index = (self.priority_player_index + 1) % self.player_order.len();
        
        // If we're back to the active player, everyone has passed
        if next_index == self.active_player_index {
            self.all_players_passed = true;
            
            // If the stack is empty and everyone has passed, move to the next phase
            if self.stack_is_empty {
                self.advance_phase()?;
            } else {
                // Resolve the top item on the stack
                // This would trigger a different system
                self.stack_is_empty = false; // This would be set by the stack system
            }
        } else {
            // Pass to the next player
            self.priority_player_index = next_index;
        }
        
        Ok(())
    }
}
}

Edge Cases and Their Handling

Player Elimination During a Turn

#![allow(unused)]
fn main() {
impl TurnManager {
    // Handle a player being eliminated
    pub fn handle_player_elimination(&mut self, eliminated_player: Entity) -> Result<(), TurnError> {
        // Remove player from the turn order
        let index = self.player_order.iter()
            .position(|&p| p == eliminated_player)
            .ok_or(TurnError::PlayerNotFound)?;
        self.player_order.remove(index);
        
        // Adjust active player index if necessary
        if index <= self.active_player_index && self.active_player_index > 0 {
            self.active_player_index -= 1;
        }
        
        // Adjust priority player index if necessary
        if index <= self.priority_player_index && self.priority_player_index > 0 {
            self.priority_player_index -= 1;
        }
        
        // Remove any extra or skipped turns for this player
        self.extra_turns.retain(|(player, _)| *player != eliminated_player);
        self.skipped_turns.remove(&eliminated_player);
        
        // If the active player was eliminated
        if index == self.active_player_index {
            // Move to the next player's turn
            let next_player = self.determine_next_player()?;
            self.active_player_index = self.player_order.iter()
                .position(|&p| p == next_player)
                .ok_or(TurnError::InvalidPlayerIndex)?;
            
            // Reset to the beginning of the turn
            self.current_phase = Phase::Beginning(BeginningStep::Untap);
            self.reset_priority_for_new_phase();
        }
        
        Ok(())
    }
}
}

Handling Multiple Extra Turns

When multiple extra turns are queued, they're processed in the order they were created:

#![allow(unused)]
fn main() {
impl TurnManager {
    // Add an extra turn to the queue
    pub fn add_extra_turn(&mut self, player: Entity, source: ExtraTurnSource) {
        self.extra_turns.push_back((player, source));
    }
}
}

Time Limits and Slow Play

#![allow(unused)]
fn main() {
impl TurnManager {
    // Check if a player has exceeded their time limit
    pub fn check_time_limit(&self, player: Entity) -> Result<bool, TurnError> {
        if let Some(limit) = self.time_limits.get(&player) {
            if let Some(start_time) = self.turn_started_at {
                return Ok(start_time.elapsed() > *limit);
            }
        }
        Ok(false)
    }
}
}

Verification and Testing Strategy

Unit Tests

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;
    
    // Test normal phase progression
    #[test]
    fn test_normal_phase_progression() {
        let mut turn_manager = setup_test_turn_manager();
        
        // Start at Beginning::Untap
        assert_eq!(turn_manager.current_phase, Phase::Beginning(BeginningStep::Untap));
        
        // Advance through all phases
        for _ in 0..12 {  // Total number of phases/steps in a turn
            turn_manager.advance_phase().unwrap();
        }
        
        // Should be back at Beginning::Untap for the next player
        assert_eq!(turn_manager.current_phase, Phase::Beginning(BeginningStep::Untap));
        assert_eq!(turn_manager.active_player_index, 1); // Next player
    }
    
    // Test extra turn handling
    #[test]
    fn test_extra_turn() {
        let mut turn_manager = setup_test_turn_manager();
        let player1 = turn_manager.player_order[0];
        
        // Add an extra turn for the current player
        turn_manager.add_extra_turn(player1, ExtraTurnSource::Rule);
        
        // Advance through a full turn
        for _ in 0..12 {
            turn_manager.advance_phase().unwrap();
        }
        
        // Should still be the same player's turn
        assert_eq!(turn_manager.active_player_index, 0);
    }
    
    // Test skipped turn
    #[test]
    fn test_skipped_turn() {
        let mut turn_manager = setup_test_turn_manager();
        let player2 = turn_manager.player_order[1];
        
        // Mark player 2's turn to be skipped
        turn_manager.skipped_turns.insert(player2);
        
        // Advance through a full turn
        for _ in 0..12 {
            turn_manager.advance_phase().unwrap();
        }
        
        // Should skip to player 3
        assert_eq!(turn_manager.active_player_index, 2);
    }
    
    // Test player elimination
    #[test]
    fn test_player_elimination() {
        let mut turn_manager = setup_test_turn_manager();
        let player2 = turn_manager.player_order[1];
        
        // Eliminate player 2
        turn_manager.handle_player_elimination(player2).unwrap();
        
        // Check player order is updated
        assert_eq!(turn_manager.player_order.len(), 3);
        assert!(!turn_manager.player_order.contains(&player2));
        
        // Complete current turn
        for _ in 0..12 {
            turn_manager.advance_phase().unwrap();
        }
        
        // Should skip from player 1 to player 3 (now at index 1)
        assert_eq!(turn_manager.active_player_index, 1);
    }
    
    // Test priority passing
    #[test]
    fn test_priority_passing() {
        let mut turn_manager = setup_test_turn_manager();
        
        // Move to a phase where priority is assigned
        turn_manager.advance_phase().unwrap(); // To Beginning::Upkeep
        
        // Active player should have priority
        assert_eq!(turn_manager.priority_player_index, 0);
        
        // Pass priority to each player
        for i in 1..4 {
            turn_manager.pass_priority().unwrap();
            assert_eq!(turn_manager.priority_player_index, i);
        }
        
        // After all players pass, should move to next phase
        turn_manager.pass_priority().unwrap();
        assert_eq!(turn_manager.current_phase, Phase::Beginning(BeginningStep::Draw));
    }
    
    // Setup helper
    fn setup_test_turn_manager() -> TurnManager {
        let player1 = Entity::from_raw(1);
        let player2 = Entity::from_raw(2);
        let player3 = Entity::from_raw(3);
        let player4 = Entity::from_raw(4);
        
        TurnManager {
            current_phase: Phase::Beginning(BeginningStep::Untap),
            active_player_index: 0,
            turn_number: 1,
            priority_player_index: 0,
            all_players_passed: true,
            stack_is_empty: true,
            player_order: vec![player1, player2, player3, player4],
            extra_turns: VecDeque::new(),
            skipped_turns: HashSet::new(),
            time_limits: HashMap::new(),
            turn_started_at: Some(Instant::now()),
            phase_history: VecDeque::new(),
            additional_phases: VecDeque::new(),
            modified_phases: HashMap::new(),
        }
    }
}
}

Integration Tests

#![allow(unused)]
fn main() {
#[cfg(test)]
mod integration_tests {
    use super::*;
    use crate::game_engine::stack::Stack;
    use crate::game_engine::state::GameState;
    
    // Test turns and stack interaction
    #[test]
    fn test_turns_with_stack() {
        let mut app = App::new();
        
        // Set up game resources
        app.insert_resource(setup_test_turn_manager());
        app.insert_resource(Stack::default());
        app.insert_resource(GameState::default());
        
        // Add relevant systems
        app.add_systems(Update, (
            phase_transition_system,
            stack_resolution_system,
            priority_system,
        ));
        
        // Simulate a turn with stack interactions
        app.update();
        
        // Add a spell to the stack
        let mut stack = app.world.resource_mut::<Stack>();
        stack.push(create_test_spell());
        
        // Verify stack is not empty
        let turn_manager = app.world.resource::<TurnManager>();
        assert!(!turn_manager.stack_is_empty);
        
        // Simulate priority passing and stack resolution
        for _ in 0..5 {
            app.update();
        }
        
        // Stack should be empty and phase should have advanced
        let turn_manager = app.world.resource::<TurnManager>();
        assert!(turn_manager.stack_is_empty);
        assert_eq!(turn_manager.current_phase, Phase::Beginning(BeginningStep::Draw));
    }
    
    // Test full turn cycle with multiple players
    #[test]
    fn test_full_turn_cycle() {
        let mut app = App::new();
        
        // Set up game resources
        app.insert_resource(setup_test_turn_manager());
        
        // Add systems
        app.add_systems(Update, phase_transition_system);
        
        // Track starting player
        let start_player = app.world.resource::<TurnManager>().active_player_index;
        
        // Simulate a full turn cycle (all players take one turn)
        for _ in 0..48 {  // 4 players × 12 phases
            app.update();
        }
        
        // Should be back to starting player
        let turn_manager = app.world.resource::<TurnManager>();
        assert_eq!(turn_manager.active_player_index, start_player);
        assert_eq!(turn_manager.turn_number, 5); // Starting turn + 4 players
    }
}
}

End-to-End Testing

#![allow(unused)]
fn main() {
#[cfg(test)]
mod e2e_tests {
    use super::*;
    use crate::test_utils::setup_full_game;
    
    // Test a full game scenario
    #[test]
    fn test_game_until_winner() {
        let mut app = setup_full_game(4); // 4 players
        
        // Run the game until only one player remains
        let max_turns = 100; // Prevent infinite loop
        for _ in 0..max_turns {
            app.update();
            
            // Check if the game has ended
            let turn_manager = app.world.resource::<TurnManager>();
            if turn_manager.player_order.len() == 1 {
                break;
            }
            
            // Simulate random player actions based on the current phase
            simulate_player_actions(&mut app);
        }
        
        // Verify we have a winner
        let turn_manager = app.world.resource::<TurnManager>();
        assert_eq!(turn_manager.player_order.len(), 1, "Game should end with one player remaining");
    }
    
    // Test complex turn interaction with time limits
    #[test]
    fn test_time_limits() {
        let mut app = setup_full_game(4);
        
        // Set time limits for all players
        {
            let mut turn_manager = app.world.resource_mut::<TurnManager>();
            for &player in &turn_manager.player_order {
                turn_manager.time_limits.insert(player, Duration::from_secs(30));
            }
        }
        
        // Fast-forward time for current player
        let current_player = {
            let turn_manager = app.world.resource::<TurnManager>();
            turn_manager.player_order[turn_manager.active_player_index]
        };
        
        // Mock time advancing past the limit for testing
        {
            let mut turn_manager = app.world.resource_mut::<TurnManager>();
            turn_manager.turn_started_at = Some(Instant::now() - Duration::from_secs(31));
        }
        
        // Add system to check time limits
        app.add_systems(Update, check_time_limits_system);
        
        // Run one update
        app.update();
        
        // Verify player's turn was ended due to time limit
        let turn_manager = app.world.resource::<TurnManager>();
        assert_ne!(turn_manager.active_player_index, 
                  turn_manager.player_order.iter().position(|&p| p == current_player).unwrap());
    }
}
}

Performance Considerations

• The TurnManager uses efficient data structures to minimize overhead:

  • HashMap for O(1) lookup of player time limits
  • VecDeque for O(1) queue operations for extra turns and phase history
  • HashSet for O(1) lookup of skipped turns

• Phase transitions are optimized to only trigger necessary game events

• Time complexity analysis:

  • Advancing phase: O(1)
  • Determining next player: O(1) in most cases, O(n) worst case (all players skip)
  • Priority passing: O(1)
  • Player elimination: O(n) where n is the number of players

Extensibility

The design allows for easy extension with new phases or rules:

• Additional phases can be added to the Phase enum
• Custom phase progression can be implemented by overriding the advance_phase method
• Game variants can be supported by modifying the TurnManager behavior

By following this implementation approach, the turn structure will robustly handle all standard Magic: The Gathering rules as well as the specific requirements of the Commander format.

Priority System

Overview

The priority system determines which player may take game actions at any given time during a Commander game. In a multiplayer format like Commander, properly managing priority is essential for maintaining game flow and ensuring all players have appropriate opportunities to respond.

Priority Rules

1. The active player receives priority at the beginning of each step or phase, except the untap and cleanup steps
2. When a player has priority, they may:
   • Cast a spell
   • Activate an ability
   • Take a special action
   • Pass priority
3. After a player casts a spell or activates an ability, they receive priority again
4. Priority passes in turn order (clockwise) from the active player
5. When all players pass priority in succession:
   • If the stack is not empty, the top item on the stack resolves, then the active player gets priority
   • If the stack is empty, the current step or phase ends and the game moves to the next step or phase

Implementation

The priority system is tracked within the TurnManager resource:

#![allow(unused)]
fn main() {
#[derive(Resource)]
pub struct TurnManager {
    // Priority system fields
    pub priority_player_index: usize,
    pub all_players_passed: bool,
    pub stack_is_empty: bool,
    
    // Step tracking for UI and timers
    pub step_started_at: std::time::Instant,
    pub auto_pass_enabled: bool,
    pub auto_pass_delay: std::time::Duration,
    
    // Other fields
    // ...
}
}

Special Priority Cases

Simultaneous Actions

When multiple players would take actions simultaneously:

1. First, the active player performs all their actions in any order they choose
2. Then, each non-active player in turn order performs their actions

Auto-Pass System

For better digital gameplay experience, the system implements an auto-pass feature:

#![allow(unused)]
fn main() {
pub fn check_auto_pass_system(
    time: Res<Time>,
    mut turn_manager: ResMut<TurnManager>,
    player_states: Query<&PlayerState>,
) {
    if turn_manager.auto_pass_enabled && 
       time.elapsed_seconds() - turn_manager.step_started_at > turn_manager.auto_pass_delay {
        // Auto-pass for the current priority player if they have no available actions
        // ...
    }
}
}

Stop Button

Players can place "stops" on specific phases and steps to ensure they receive priority, even when auto-pass is enabled:

#![allow(unused)]
fn main() {
#[derive(Component)]
pub struct PlayerStops {
    pub phases: HashMap<Phase, bool>,
    // Additional stop settings
}
}

UI Representation

The priority system is visually represented to players through:

1. A highlighted border around the active player's avatar
2. A timer indicator showing how long the current player has had priority
3. Special effects when priority passes
4. Visual cues for auto-pass situations

Multiplayer Considerations

In Commander, the priority system manages additional complexity:

• Tracking priority across 3-6 players
• Handling "table talk" periods during complex game states
• Supporting take-backs by mutual agreement (optional house rule)
• Managing disconnected players in digital play

Multiplayer Turns in Commander

This document explains how multiplayer turns are implemented in the Rummage game engine for the Commander format.

Multiplayer Turn Structure

Commander is designed as a multiplayer format, typically played with 3-6 players. The multiplayer turn structure follows these rules:

1. Players take turns in clockwise order, starting from a randomly determined first player
2. Turn order remains fixed throughout the game unless modified by card effects
3. All standard turn phases occur during each player's turn
4. Players can act during other players' turns when they have priority
5. Some effects specifically reference "each player" or "each opponent" which have multiplayer implications

Turn Order Implementation

#![allow(unused)]
fn main() {
/// Resource that tracks turn order
#[derive(Resource, Debug, Clone)]
pub struct TurnOrder {
    /// List of players in turn order
    pub players: Vec<Entity>,
    /// Current player index in the players list
    pub current_player_index: usize,
    /// Direction of turn progression (1 for clockwise, -1 for counter-clockwise)
    pub direction: i32,
}

impl TurnOrder {
    /// Creates a new turn order with the specified players
    pub fn new(players: Vec<Entity>) -> Self {
        Self {
            players,
            current_player_index: 0,
            direction: 1,
        }
    }
    
    /// Gets the current player
    pub fn current_player(&self) -> Entity {
        self.players[self.current_player_index]
    }
    
    /// Advances to the next player's turn
    pub fn advance(&mut self) {
        let len = self.players.len() as i32;
        self.current_player_index = (
            (self.current_player_index as i32 + self.direction).rem_euclid(len)
        ) as usize;
    }
    
    /// Reverses the turn order direction
    pub fn reverse(&mut self) {
        self.direction = -self.direction;
    }
    
    /// Shuffles the player order
    pub fn shuffle(&mut self, rng: &mut impl Rng) {
        self.players.shuffle(rng);
        // Maintain current player at index 0 after shuffle
        let current = self.current_player();
        let current_pos = self.players.iter().position(|&p| p == current).unwrap();
        self.players.swap(0, current_pos);
        self.current_player_index = 0;
    }
    
    /// Skips the next player's turn
    pub fn skip_next(&mut self) {
        self.advance();
    }
    
    /// Returns an iterator over all players starting from the current player
    pub fn iter_from_current(&self) -> impl Iterator<Item = Entity> + '_ {
        let len = self.players.len();
        (0..len).map(move |offset| {
            let index = (self.current_player_index + offset) % len;
            self.players[index]
        })
    }
    
    /// Returns an iterator over all opponents of the current player
    pub fn iter_opponents(&self) -> impl Iterator<Item = Entity> + '_ {
        let current = self.current_player();
        self.players.iter().copied().filter(move |&p| p != current)
    }
}
}

Turn Advancement System

#![allow(unused)]
fn main() {
/// System that advances to the next player's turn
pub fn advance_turn(
    mut turn_order: ResMut<TurnOrder>,
    mut turn_phase: ResMut<TurnPhase>,
    mut turn_events: EventWriter<TurnEvent>,
    mut game_state: ResMut<GameState>,
    time: Res<Time>,
) {
    if game_state.current_state != GameStateType::EndOfTurn {
        return;
    }
    
    // Get current player before advancing
    let previous_player = turn_order.current_player();
    
    // Advance to next player
    turn_order.advance();
    let next_player = turn_order.current_player();
    
    // Reset turn phase to beginning of turn
    *turn_phase = TurnPhase::Beginning(BeginningPhase::Untap);
    
    // Update game state
    game_state.current_state = GameStateType::ActiveTurn;
    game_state.active_player = next_player;
    
    // Send events
    turn_events.send(TurnEvent::TurnEnded { player: previous_player });
    turn_events.send(TurnEvent::TurnBegan { player: next_player });
}
}

Multiplayer-Specific Mechanics

Turn-Based Effects

Some effects need to track when players take turns:

#![allow(unused)]
fn main() {
/// Component for effects that trigger at the beginning of a player's turn
#[derive(Component, Debug, Clone)]
pub struct BeginningOfTurnTrigger {
    /// Whether this triggers on the controller's turn only
    pub controller_only: bool,
    /// Whether this triggers on opponents' turns only
    pub opponents_only: bool,
    /// Function to execute when triggered
    pub effect: fn(Commands, Entity) -> (),
}

/// System that handles beginning of turn triggers
pub fn handle_beginning_of_turn_triggers(
    mut commands: Commands,
    turn_order: Res<TurnOrder>,
    turn_phase: Res<TurnPhase>,
    triggers: Query<(Entity, &BeginningOfTurnTrigger, &Owner)>,
) {
    // Only execute during the beginning of turn phase
    if !matches!(turn_phase.as_ref(), TurnPhase::Beginning(BeginningPhase::Upkeep)) {
        return;
    }
    
    let current_player = turn_order.current_player();
    
    for (entity, trigger, owner) in triggers.iter() {
        let is_owner_turn = owner.0 == current_player;
        
        // Check if trigger condition is met
        if (trigger.controller_only && is_owner_turn) ||
           (trigger.opponents_only && !is_owner_turn) ||
           (!trigger.controller_only && !trigger.opponents_only) {
            (trigger.effect)(commands, entity);
        }
    }
}
}

Simultaneous Effects

In multiplayer games, effects that affect all players need special handling:

#![allow(unused)]
fn main() {
/// Handles effects that apply to all players simultaneously
pub fn handle_global_effects(
    mut commands: Commands,
    players: Query<Entity, With<Player>>,
    global_effects: Query<(Entity, &GlobalEffect)>,
) {
    for (effect_entity, global_effect) in global_effects.iter() {
        match global_effect.target_type {
            GlobalTargetType::AllPlayers => {
                for player in players.iter() {
                    (global_effect.apply_effect)(commands, effect_entity, player);
                }
            },
            GlobalTargetType::AllOpponents => {
                let turn_order = commands.world().resource::<TurnOrder>();
                let current_player = turn_order.current_player();
                
                for player in players.iter() {
                    if player != current_player {
                        (global_effect.apply_effect)(commands, effect_entity, player);
                    }
                }
            },
            // Other global target types...
        }
    }
}
}

Special Turn Interactions

Extra Turns

Commander allows for extra turn effects:

#![allow(unused)]
fn main() {
#[derive(Resource, Debug)]
pub struct ExtraTurns {
    /// Queue of players taking extra turns
    pub queue: VecDeque<Entity>,
}

/// System that handles extra turn insertion
pub fn handle_extra_turns(
    mut turn_order: ResMut<TurnOrder>,
    mut extra_turns: ResMut<ExtraTurns>,
    mut turn_events: EventWriter<TurnEvent>,
) {
    if let Some(player) = extra_turns.queue.pop_front() {
        // Current player takes an extra turn
        let current = turn_order.current_player();
        if player == current {
            turn_events.send(TurnEvent::ExtraTurn { player });
        } else {
            // Another player takes the next turn
            // Temporarily modify turn order
            let current_index = turn_order.current_player_index;
            let player_index = turn_order.players.iter().position(|&p| p == player).unwrap();
            turn_order.current_player_index = player_index;
            turn_events.send(TurnEvent::ExtraTurn { player });
            
            // Store original order to restore after the extra turn
            commands.insert_resource(PendingTurnRestoration {
                restore_index: current_index,
            });
        }
    }
}
}

Turn Modifications

Some cards can modify turn order or skip turns:

#![allow(unused)]
fn main() {
/// Event for turn order modifications
#[derive(Event, Debug, Clone)]
pub enum TurnOrderEvent {
    /// Reverses turn order direction
    Reverse,
    /// Skips the next player's turn
    SkipNext,
    /// Takes an extra turn after the current one
    ExtraTurn { player: Entity },
    /// Exchanges turns between players
    ExchangeTurn { player_a: Entity, player_b: Entity },
}

/// System that handles turn order modifications
pub fn handle_turn_modifications(
    mut turn_order: ResMut<TurnOrder>,
    mut extra_turns: ResMut<ExtraTurns>,
    mut turn_events: EventReader<TurnOrderEvent>,
    mut game_events: EventWriter<GameEvent>,
) {
    for event in turn_events.read() {
        match event {
            TurnOrderEvent::Reverse => {
                turn_order.reverse();
                game_events.send(GameEvent::TurnOrderReversed);
            },
            TurnOrderEvent::SkipNext => {
                turn_order.skip_next();
                game_events.send(GameEvent::TurnSkipped);
            },
            TurnOrderEvent::ExtraTurn { player } => {
                extra_turns.queue.push_back(*player);
                game_events.send(GameEvent::ExtraTurnAdded { player: *player });
            },
            TurnOrderEvent::ExchangeTurn { player_a, player_b } => {
                let pos_a = turn_order.players.iter().position(|&p| p == *player_a).unwrap();
                let pos_b = turn_order.players.iter().position(|&p| p == *player_b).unwrap();
                turn_order.players.swap(pos_a, pos_b);
                game_events.send(GameEvent::TurnOrderModified);
            },
        }
    }
}
}

UI Representation

Multiplayer turns are visually represented in the UI:

1. Turn Order Display: Shows all players in order with the current player highlighted
2. Active Player Indicator: Clearly highlights whose turn it is
3. Turn Direction Indicator: Shows the current direction of play (clockwise/counter-clockwise)
4. Extra Turn Queue: Displays any pending extra turns
5. Phase Tracker: Shows the current phase of the active player's turn

Testing

Example Test

#![allow(unused)]
fn main() {
#[test]
fn test_multiplayer_turn_order() {
    // Create test app with required systems
    let mut app = App::new();
    app.add_systems(Update, advance_turn)
        .add_event::<TurnEvent>()
        .init_resource::<GameState>();
    
    // Create four players for a typical 4-player game
    let player1 = app.world.spawn_empty().id();
    let player2 = app.world.spawn_empty().id();
    let player3 = app.world.spawn_empty().id();
    let player4 = app.world.spawn_empty().id();
    
    let players = vec![player1, player2, player3, player4];
    
    // Initialize turn order
    app.insert_resource(TurnOrder::new(players.clone()));
    app.insert_resource(TurnPhase::Ending(EndingPhase::End));
    
    // Set game state to end of turn to trigger advancement
    let mut game_state = GameState::default();
    game_state.current_state = GameStateType::EndOfTurn;
    app.insert_resource(game_state);
    
    // First turn should be player1
    let turn_order = app.world.resource::<TurnOrder>();
    assert_eq!(turn_order.current_player(), player1);
    
    // Advance turn
    app.update();
    
    // Should now be player2's turn
    let turn_order = app.world.resource::<TurnOrder>();
    assert_eq!(turn_order.current_player(), player2);
    
    // Test turn events
    let events = app.world.resource::<Events<TurnEvent>>();
    let mut reader = events.get_reader();
    
    let mut saw_end = false;
    let mut saw_begin = false;
    
    for event in reader.read(&events) {
        match event {
            TurnEvent::TurnEnded { player } => {
                assert_eq!(*player, player1);
                saw_end = true;
            },
            TurnEvent::TurnBegan { player } => {
                assert_eq!(*player, player2);
                saw_begin = true;
            },
            _ => {}
        }
    }
    
    assert!(saw_end, "Should have seen turn ended event");
    assert!(saw_begin, "Should have seen turn began event");
}

#[test]
fn test_reversed_turn_order() {
    // Similar test setup
    let mut app = App::new();
    // ...
    
    // Insert reversed turn order
    let mut turn_order = TurnOrder::new(players.clone());
    turn_order.reverse(); // Direction becomes -1
    app.insert_resource(turn_order);
    
    // Advance from player1
    app.update();
    
    // Should now be player4's turn (counter-clockwise)
    let turn_order = app.world.resource::<TurnOrder>();
    assert_eq!(turn_order.current_player(), player4);
}
}

Summary

Multiplayer turns in Commander are implemented with a flexible system that:

1. Maintains proper turn order in multiplayer games
2. Supports direction changes (clockwise/counter-clockwise)
3. Handles extra turns and turn skipping
4. Processes effects that affect multiple players
5. Provides clear UI indicators for turn progression
6. Is thoroughly tested for all turn modification scenarios

Extra Turns and Turn Modifications

Overview

Commander implements various turn modification effects from Magic: The Gathering, including extra turns, skipped turns, and modified turn structures. These effects are particularly impactful in a multiplayer environment.

Extra Turns

Extra turns are implemented through a queue system in the TurnManager:

#![allow(unused)]
fn main() {
#[derive(Resource)]
pub struct TurnManager {
    // Other fields...
    pub extra_turns: VecDeque<(Entity, ExtraTurnSource)>,
    pub skipped_turns: HashSet<Entity>,
}

#[derive(Debug, Clone)]
pub struct ExtraTurnSource {
    pub source_card: Entity,
    pub extra_turn_type: ExtraTurnType,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ExtraTurnType {
    Standard,
    CombatOnly,
    WithRestrictions(Vec<TurnRestriction>),
}
}

When a player would gain an extra turn:

1. The extra turn is added to the queue
2. When the current turn ends, the system checks the queue before advancing to the next player's turn
3. If there are extra turns queued, the player specified in the queue takes their extra turn
4. After all extra turns are complete, normal turn order resumes

Turn Restrictions

Certain cards can impose restrictions on turns, implemented through the TurnRestriction enum:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum TurnRestriction {
    NoUntap,
    NoUpkeep,
    NoDraw,
    NoMainPhase,
    NoCombat,
    MaxSpells(u32),
    NoActivatedAbilities,
    MustAttack,
    CantAttack,
    NoArtifactsEnchantmentsCreatures,
    LoseAtEndStep,
}
}

These restrictions can be associated with specific turns, including extra turns.

Skipped Turns

The system also tracks turns that should be skipped:

#![allow(unused)]
fn main() {
pub fn process_turn_transition(
    mut turn_manager: ResMut<TurnManager>,
    // Other parameters...
) {
    // Find the next active player
    let mut next_player_index = (turn_manager.active_player_index + 1) % turn_manager.player_order.len();
    let next_player = turn_manager.player_order[next_player_index];
    
    // Check for skipped turns
    if turn_manager.skipped_turns.contains(&next_player) {
        turn_manager.skipped_turns.remove(&next_player);
        // Skip to the player after the one who would skip
        next_player_index = (next_player_index + 1) % turn_manager.player_order.len();
    }
    
    // Check for extra turns first
    if !turn_manager.extra_turns.is_empty() {
        let (extra_turn_player, source) = turn_manager.extra_turns.pop_front().unwrap();
        // Process the extra turn...
    } else {
        // Set the next player as active
        turn_manager.active_player_index = next_player_index;
    }
    
    // Reset for new turn
    turn_manager.current_phase = Phase::Beginning(BeginningStep::Untap);
    turn_manager.turn_number += 1;
}
}

Additional Phase Modifications

The system supports other phase modifications:

• Additional combat phases
• Phase repetition
• Phase reordering (in specific cases)
• Phase duration modifications

Multiplayer Impact

Extra turns and turn modifications have significant impact in Commander:

• Political considerations when taking extra turns
• More targets for "target player skips their next turn" effects
• Greater variance in game length due to turn manipulation
• House rules regarding excessive turn manipulation

Implementation Details

The turn modification system integrates with the event system to ensure proper triggers occur:

#![allow(unused)]
fn main() {
pub fn extra_turn_system(
    mut commands: Commands,
    mut turn_manager: ResMut<TurnManager>,
    mut extra_turn_events: EventReader<ExtraTurnEvent>,
) {
    for event in extra_turn_events.iter() {
        turn_manager.extra_turns.push_back((event.player, event.source.clone()));
    }
}
}

Cards that grant or modify turns dispatch appropriate events that are handled by these systems.

Phase Management

Phase and Step Definitions

The Commander implementation uses a hierarchical structure of phases and steps that closely follows the official Magic rules:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Phase {
    Beginning(BeginningStep),
    Precombat(PrecombatStep),
    Combat(CombatStep),
    Postcombat(PostcombatStep),
    Ending(EndingStep),
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BeginningStep {
    Untap,
    Upkeep,
    Draw,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PrecombatStep {
    Main,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CombatStep {
    Beginning,
    DeclareAttackers,
    DeclareBlockers,
    CombatDamage,
    End,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PostcombatStep {
    Main,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EndingStep {
    End,
    Cleanup,
}
}

Phase Transitions

Phase transitions are managed by the turn system and occur when:

1. All players have passed priority with an empty stack
2. Certain turn-based actions are completed
3. Special effects cause phase skipping or addition

Phase-Specific Actions

Each phase and step has specific turn-based actions that occur at its beginning:

Beginning Phase

Untap Step

• The active player untaps all permanents they control
• No players receive priority during this step
• "At the beginning of your untap step" triggered abilities trigger

Upkeep Step

• "At the beginning of your upkeep" triggered abilities trigger
• Players receive priority

Draw Step

• Active player draws a card
• "At the beginning of your draw step" triggered abilities trigger
• Players receive priority

Main Phases

• Active player may play land (once per turn)
• Players may cast spells and activate abilities
• No automatic actions occur

Combat Phase

• Detailed in the Combat System documentation

Ending Phase

End Step

• "At the beginning of your end step" triggered abilities trigger
• Players receive priority

Cleanup Step

• Active player discards down to maximum hand size
• Damage is removed from permanents
• "Until end of turn" effects end
• Normally, no player receives priority during this step
  • If any state-based actions are performed or triggered abilities trigger, players do receive priority

Special Phase Handling

The phase system accounts for special cases:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum TurnRestriction {
    NoUntap,
    NoUpkeep,
    NoDraw,
    NoMainPhase,
    NoCombat,
    MaxSpells(u32),
    // Other restrictions
}
}

These phase restrictions can be applied through card effects and are managed by the TurnManager.

Multiplayer Turn Handling

Overview

Commander's multiplayer nature introduces special considerations for turn management, particularly regarding turn order, player elimination, and simultaneous effects. This document outlines how the turn system handles these multiplayer-specific scenarios.

Player Order Management

Turn order in Commander follows a clockwise rotation from a randomly determined starting player. The turn order is maintained in the TurnManager:

#![allow(unused)]
fn main() {
#[derive(Resource)]
pub struct TurnManager {
    // Other fields...
    pub player_order: Vec<Entity>,
}
}

At game initialization, the player order is randomized:

#![allow(unused)]
fn main() {
fn initialize_turn_order(
    mut commands: Commands,
    player_query: Query<Entity, With<Player>>,
) {
    let mut player_entities: Vec<Entity> = player_query.iter().collect();
    // Randomize the order
    player_entities.shuffle(&mut thread_rng());
    
    commands.insert_resource(TurnManager {
        player_order: player_entities,
        // Initialize other fields...
    });
}
}

Player Elimination Handling

When a player is eliminated from the game, the turn system must adjust the turn order and potentially the active player and priority indicators:

#![allow(unused)]
fn main() {
fn handle_player_elimination(
    mut commands: Commands,
    mut elimination_events: EventReader<PlayerEliminationEvent>,
    mut turn_manager: ResMut<TurnManager>,
) {
    for event in elimination_events.read() {
        let eliminated_player = event.player;
        
        // Remove player from turn order
        if let Some(pos) = turn_manager.player_order.iter().position(|&p| p == eliminated_player) {
            turn_manager.player_order.remove(pos);
            
            // Adjust current active and priority indices if needed
            if pos <= turn_manager.active_player_index {
                turn_manager.active_player_index = 
                    (turn_manager.active_player_index - 1) % turn_manager.player_order.len();
            }
            
            if pos <= turn_manager.priority_player_index {
                turn_manager.priority_player_index = 
                    (turn_manager.priority_player_index - 1) % turn_manager.player_order.len();
            }
        }
    }
}
}

Simultaneous Effects

In Commander, many effects can happen simultaneously across multiple players. The system handles these according to Magic's APNAP (Active Player, Non-Active Player) rule:

#![allow(unused)]
fn main() {
fn handle_simultaneous_effects(
    turn_manager: Res<TurnManager>,
    mut simultaneous_events: EventReader<SimultaneousEffectEvent>,
    mut commands: Commands,
) {
    let mut effect_queue = Vec::new();
    
    // Collect all simultaneous effects
    for event in simultaneous_events.read() {
        effect_queue.push((event.player, event.effect.clone()));
    }
    
    // Sort by APNAP order
    effect_queue.sort_by(|(player_a, _), (player_b, _)| {
        let active_player = turn_manager.player_order[turn_manager.active_player_index];
        
        if *player_a == active_player {
            return Ordering::Less;
        }
        if *player_b == active_player {
            return Ordering::Greater;
        }
        
        // For non-active players, compare positions in turn order
        let pos_a = turn_manager.player_order.iter().position(|&p| p == *player_a).unwrap();
        let pos_b = turn_manager.player_order.iter().position(|&p| p == *player_b).unwrap();
        pos_a.cmp(&pos_b)
    });
    
    // Process effects in sorted order
    for (player, effect) in effect_queue {
        // Process each effect...
    }
}
}

Multi-Player Variants

The turn system supports different Commander variants:

• Free-for-All: Standard Commander with turn order passing clockwise
• Two-Headed Giant: Teams share turns and life totals
• Star: Five players with win conditions based on eliminating opposing "colors"
• Archenemy: One player versus all others, with the Archenemy having access to scheme cards

Each variant may modify the TurnManager initialization and behavior:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum GameVariant {
    FreeForAll,
    TwoHeadedGiant,
    Star,
    Archenemy,
    // Other variants
}

// The variant affects turn handling
pub fn initialize_turn_manager(
    variant: GameVariant,
    players: Vec<Entity>,
) -> TurnManager {
    match variant {
        GameVariant::TwoHeadedGiant => {
            // Team members share turns
            // ...
        },
        GameVariant::Archenemy => {
            // Archenemy goes first
            // ...
        },
        _ => {
            // Standard initialization
            // ...
        }
    }
}
}

Multiplayer-Specific Considerations

The turn system accounts for multiplayer-specific mechanics:

• Range of Influence: Limited in some variants (like Star)
• Shared Team Turns: In variants like Two-Headed Giant
• Table Politics: Support for game actions like voting
• Monarch: Special designation that passes between players
• Initiative: Tracking which player has the initiative in Undercity dungeon scenarios

Turn and Phase Tests

This section contains tests related to the turn structure and phase mechanics in the Commander format, with a focus on multiplayer interactions.

Multiplayer Turn Structure Tests

The Multiplayer Turn Structure Tests validate the proper handling of turns in a multiplayer environment, including:

• Turn order in multiplayer games
• Turn modification effects (extra turns, skipped turns)
• Phase progression in various game states
• Proper handling of priority in multiplayer scenarios
• Player elimination effects on turn structure

These tests ensure that the multiplayer aspects of the Commander format's turn structure function correctly within the game engine.

Multiplayer Turn Structure Tests

Overview

This document outlines test cases for Commander's multiplayer turn structure, focusing on turn order, extra turns, and phase management in a multiplayer environment. These tests ensure the game properly handles turn-based interactions in a format that can have 3-6 players.

Test Case: Basic Turn Order

Test: Turn Order in Multiplayer Game

#![allow(unused)]
fn main() {
#[test]
fn test_multiplayer_turn_order() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (update_turn_order, next_turn, check_active_player));
       
    // Create a multiplayer game with 4 players
    let player1 = app.world.spawn((
        Player { id: 1 },
        PlayerName("Player 1".to_string()),
    )).id();
    
    let player2 = app.world.spawn((
        Player { id: 2 },
        PlayerName("Player 2".to_string()),
    )).id();
    
    let player3 = app.world.spawn((
        Player { id: 3 },
        PlayerName("Player 3".to_string()),
    )).id();
    
    let player4 = app.world.spawn((
        Player { id: 4 },
        PlayerName("Player 4".to_string()),
    )).id();
    
    // Set up turn order
    app.insert_resource(TurnOrder {
        players: vec![player1, player2, player3, player4],
        current_index: 0,
    });
    
    app.insert_resource(TurnManager {
        current_phase: Phase::Beginning(BeginningPhaseStep::Untap),
        active_player: player1,
    });
    
    // Validate initial active player
    let turn_manager = app.world.resource::<TurnManager>();
    assert_eq!(turn_manager.active_player, player1);
    
    // Execute a full turn and move to next player
    app.world.send_event(EndTurnEvent);
    app.update();
    
    // Verify active player changed to player 2
    let turn_manager = app.world.resource::<TurnManager>();
    assert_eq!(turn_manager.active_player, player2);
    
    // Execute another turn
    app.world.send_event(EndTurnEvent);
    app.update();
    
    // Verify active player changed to player 3
    let turn_manager = app.world.resource::<TurnManager>();
    assert_eq!(turn_manager.active_player, player3);
    
    // Simulate a full rotation
    app.world.send_event(EndTurnEvent);
    app.update();
    app.world.send_event(EndTurnEvent);
    app.update();
    
    // Should be back to player 1
    let turn_manager = app.world.resource::<TurnManager>();
    assert_eq!(turn_manager.active_player, player1);
}
}

Test Case: Player Elimination

Test: Removing a Player from Turn Order

#![allow(unused)]
fn main() {
#[test]
fn test_player_elimination() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (update_turn_order, handle_player_elimination, next_turn));
       
    // Create a multiplayer game with 4 players
    let player1 = app.world.spawn(Player { id: 1 }).id();
    let player2 = app.world.spawn(Player { id: 2 }).id();
    let player3 = app.world.spawn(Player { id: 3 }).id();
    let player4 = app.world.spawn(Player { id: 4 }).id();
    
    // Set up turn order
    app.insert_resource(TurnOrder {
        players: vec![player1, player2, player3, player4],
        current_index: 0,
    });
    
    app.insert_resource(TurnManager {
        current_phase: Phase::Beginning(BeginningPhaseStep::Untap),
        active_player: player1,
    });
    
    // Player 2 is eliminated
    app.world.send_event(PlayerEliminatedEvent { player: player2 });
    app.update();
    
    // Verify turn order adjusted
    let turn_order = app.world.resource::<TurnOrder>();
    assert_eq!(turn_order.players, vec![player1, player3, player4]);
    
    // Current player should still be player 1
    let turn_manager = app.world.resource::<TurnManager>();
    assert_eq!(turn_manager.active_player, player1);
    
    // End turn
    app.world.send_event(EndTurnEvent);
    app.update();
    
    // Verify active player skipped player 2 and is now player 3
    let turn_manager = app.world.resource::<TurnManager>();
    assert_eq!(turn_manager.active_player, player3);
}
}

Test: Eliminating the Active Player

#![allow(unused)]
fn main() {
#[test]
fn test_active_player_elimination() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (update_turn_order, handle_player_elimination, next_turn));
       
    // Create a multiplayer game with 4 players
    let player1 = app.world.spawn(Player { id: 1 }).id();
    let player2 = app.world.spawn(Player { id: 2 }).id();
    let player3 = app.world.spawn(Player { id: 3 }).id();
    let player4 = app.world.spawn(Player { id: 4 }).id();
    
    // Set up turn order
    app.insert_resource(TurnOrder {
        players: vec![player1, player2, player3, player4],
        current_index: 0,
    });
    
    app.insert_resource(TurnManager {
        current_phase: Phase::Beginning(BeginningPhaseStep::Untap),
        active_player: player1,
    });
    
    // Active player is eliminated
    app.world.send_event(PlayerEliminatedEvent { player: player1 });
    app.update();
    
    // Verify turn order adjusted and active player changed
    let turn_order = app.world.resource::<TurnOrder>();
    assert_eq!(turn_order.players, vec![player2, player3, player4]);
    
    let turn_manager = app.world.resource::<TurnManager>();
    assert_eq!(turn_manager.active_player, player2);
}
}

Test Case: Extra Turns

Test: Player Takes an Extra Turn

#![allow(unused)]
fn main() {
#[test]
fn test_extra_turn() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (update_turn_order, handle_extra_turns, next_turn));
       
    // Create a multiplayer game with 4 players
    let player1 = app.world.spawn(Player { id: 1 }).id();
    let player2 = app.world.spawn(Player { id: 2 }).id();
    let player3 = app.world.spawn(Player { id: 3 }).id();
    let player4 = app.world.spawn(Player { id: 4 }).id();
    
    // Set up turn order
    app.insert_resource(TurnOrder {
        players: vec![player1, player2, player3, player4],
        current_index: 0,
    });
    
    app.insert_resource(TurnManager {
        current_phase: Phase::Beginning(BeginningPhaseStep::Untap),
        active_player: player1,
    });
    
    app.insert_resource(ExtraTurns::default());
    
    // Player 1 gets an extra turn
    app.world.send_event(ExtraTurnEvent { 
        player: player1,
        count: 1,
        source: EntitySource { entity: Entity::PLACEHOLDER },
    });
    
    // End current turn
    app.world.send_event(EndTurnEvent);
    app.update();
    
    // Verify player 1 gets an extra turn instead of going to player 2
    let turn_manager = app.world.resource::<TurnManager>();
    assert_eq!(turn_manager.active_player, player1);
    
    // End extra turn
    app.world.send_event(EndTurnEvent);
    app.update();
    
    // Now it should go to player 2
    let turn_manager = app.world.resource::<TurnManager>();
    assert_eq!(turn_manager.active_player, player2);
}
}

Test: Multiple Extra Turns Across Players

#![allow(unused)]
fn main() {
#[test]
fn test_multiple_extra_turns() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (update_turn_order, handle_extra_turns, next_turn));
       
    // Create a multiplayer game with 4 players
    let player1 = app.world.spawn(Player { id: 1 }).id();
    let player2 = app.world.spawn(Player { id: 2 }).id();
    let player3 = app.world.spawn(Player { id: 3 }).id();
    let player4 = app.world.spawn(Player { id: 4 }).id();
    
    // Set up turn order
    app.insert_resource(TurnOrder {
        players: vec![player1, player2, player3, player4],
        current_index: 0,
    });
    
    app.insert_resource(TurnManager {
        current_phase: Phase::Beginning(BeginningPhaseStep::Untap),
        active_player: player1,
    });
    
    app.insert_resource(ExtraTurns::default());
    
    // Player 1 grants an extra turn to player 3
    app.world.send_event(ExtraTurnEvent { 
        player: player3,
        count: 1,
        source: EntitySource { entity: Entity::PLACEHOLDER },
    });
    
    // Player 2 grants an extra turn to themselves
    app.world.send_event(ExtraTurnEvent { 
        player: player2,
        count: 1,
        source: EntitySource { entity: Entity::PLACEHOLDER },
    });
    
    // End current turn (player 1)
    app.world.send_event(EndTurnEvent);
    app.update();
    
    // Regular turn order goes to player 2
    let turn_manager = app.world.resource::<TurnManager>();
    assert_eq!(turn_manager.active_player, player2);
    
    // End turn (player 2)
    app.world.send_event(EndTurnEvent);
    app.update();
    
    // Player 2's extra turn happens before moving to player 3
    let turn_manager = app.world.resource::<TurnManager>();
    assert_eq!(turn_manager.active_player, player2);
    
    // End extra turn (player 2)
    app.world.send_event(EndTurnEvent);
    app.update();
    
    // Now it's player 3's turn
    let turn_manager = app.world.resource::<TurnManager>();
    assert_eq!(turn_manager.active_player, player3);
    
    // End turn (player 3)
    app.world.send_event(EndTurnEvent);
    app.update();
    
    // Player 3 gets extra turn
    let turn_manager = app.world.resource::<TurnManager>();
    assert_eq!(turn_manager.active_player, player3);
}
}

Test Case: Phase Management

Test: Phase Progression Through a Turn

#![allow(unused)]
fn main() {
#[test]
fn test_phase_progression() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (update_phase, handle_phase_transitions));
       
    // Create player
    let player = app.world.spawn(Player {}).id();
    
    // Set up turn manager
    app.insert_resource(TurnManager {
        current_phase: Phase::Beginning(BeginningPhaseStep::Untap),
        active_player: player,
    });
    
    // Progress through beginning phase
    app.update();
    assert_eq!(app.world.resource::<TurnManager>().current_phase, Phase::Beginning(BeginningPhaseStep::Untap));
    
    app.world.send_event(NextPhaseEvent);
    app.update();
    assert_eq!(app.world.resource::<TurnManager>().current_phase, Phase::Beginning(BeginningPhaseStep::Upkeep));
    
    app.world.send_event(NextPhaseEvent);
    app.update();
    assert_eq!(app.world.resource::<TurnManager>().current_phase, Phase::Beginning(BeginningPhaseStep::Draw));
    
    // Move to main phase
    app.world.send_event(NextPhaseEvent);
    app.update();
    assert_eq!(app.world.resource::<TurnManager>().current_phase, Phase::PreCombatMain);
    
    // Move to combat
    app.world.send_event(NextPhaseEvent);
    app.update();
    assert_eq!(app.world.resource::<TurnManager>().current_phase, Phase::Combat(CombatStep::Beginning));
    
    // Cycle through combat steps
    app.world.send_event(NextPhaseEvent);
    app.update();
    assert_eq!(app.world.resource::<TurnManager>().current_phase, Phase::Combat(CombatStep::DeclareAttackers));
    
    app.world.send_event(NextPhaseEvent);
    app.update();
    assert_eq!(app.world.resource::<TurnManager>().current_phase, Phase::Combat(CombatStep::DeclareBlockers));
    
    app.world.send_event(NextPhaseEvent);
    app.update();
    assert_eq!(app.world.resource::<TurnManager>().current_phase, Phase::Combat(CombatStep::CombatDamage));
    
    app.world.send_event(NextPhaseEvent);
    app.update();
    assert_eq!(app.world.resource::<TurnManager>().current_phase, Phase::Combat(CombatStep::End));
    
    // Move to post-combat main
    app.world.send_event(NextPhaseEvent);
    app.update();
    assert_eq!(app.world.resource::<TurnManager>().current_phase, Phase::PostCombatMain);
    
    // Move to end step
    app.world.send_event(NextPhaseEvent);
    app.update();
    assert_eq!(app.world.resource::<TurnManager>().current_phase, Phase::Ending(EndingPhaseStep::End));
    
    app.world.send_event(NextPhaseEvent);
    app.update();
    assert_eq!(app.world.resource::<TurnManager>().current_phase, Phase::Ending(EndingPhaseStep::Cleanup));
}
}

Test: Turn-Based Actions in Each Phase

#![allow(unused)]
fn main() {
#[test]
fn test_turn_based_actions() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (handle_untap_step, handle_draw_step, handle_phase_transitions));
       
    // Create player with permanents
    let player = app.world.spawn((
        Player {},
        Hand::default(),
    )).id();
    
    // Create some tapped permanents
    let permanent1 = app.world.spawn((
        Card { name: "Permanent 1".to_string() },
        Permanent,
        Status { tapped: true },
        Controller { player },
    )).id();
    
    let permanent2 = app.world.spawn((
        Card { name: "Permanent 2".to_string() },
        Permanent,
        Status { tapped: true },
        Controller { player },
    )).id();
    
    // Set up turn manager in untap step
    app.insert_resource(TurnManager {
        current_phase: Phase::Beginning(BeginningPhaseStep::Untap),
        active_player: player,
    });
    
    // Process untap step
    app.update();
    
    // Verify permanents were untapped
    let status1 = app.world.get::<Status>(permanent1).unwrap();
    let status2 = app.world.get::<Status>(permanent2).unwrap();
    assert!(!status1.tapped);
    assert!(!status2.tapped);
    
    // Move to draw step
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Beginning(BeginningPhaseStep::Draw);
    
    // Create library with cards
    let card1 = app.world.spawn((
        Card { name: "Card 1".to_string() },
        Zone::Library,
        Owner { player },
    )).id();
    
    let library = app.world.spawn((
        Library { owner: player },
        Cards { entities: vec![card1] },
    )).id();
    
    // Process draw step
    app.update();
    
    // Verify card was drawn
    assert_eq!(app.world.get::<Zone>(card1).unwrap(), &Zone::Hand);
    let hand = app.world.get::<Hand>(player).unwrap();
    assert_eq!(hand.cards.len(), 1);
    assert!(hand.cards.contains(&card1));
}
}

Test Case: Priority System

Test: Priority Passing in Turn Order

#![allow(unused)]
fn main() {
#[test]
fn test_priority_passing() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (handle_priority, update_turn_order));
       
    // Create a multiplayer game with 4 players
    let player1 = app.world.spawn(Player { id: 1 }).id();
    let player2 = app.world.spawn(Player { id: 2 }).id();
    let player3 = app.world.spawn(Player { id: 3 }).id();
    let player4 = app.world.spawn(Player { id: 4 }).id();
    
    // Set up turn order
    app.insert_resource(TurnOrder {
        players: vec![player1, player2, player3, player4],
        current_index: 0,
    });
    
    app.insert_resource(TurnManager {
        current_phase: Phase::PreCombatMain,
        active_player: player1,
    });
    
    app.insert_resource(PrioritySystem {
        has_priority: player1,
        stack_is_empty: true,
        all_players_passed: false,
    });
    
    // Active player passes priority
    app.world.send_event(PriorityPassedEvent { player: player1 });
    app.update();
    
    // Check priority passed to next player
    let priority = app.world.resource::<PrioritySystem>();
    assert_eq!(priority.has_priority, player2);
    
    // Second player passes
    app.world.send_event(PriorityPassedEvent { player: player2 });
    app.update();
    
    // Check priority passed to next player
    let priority = app.world.resource::<PrioritySystem>();
    assert_eq!(priority.has_priority, player3);
    
    // Third player passes
    app.world.send_event(PriorityPassedEvent { player: player3 });
    app.update();
    
    // Check priority passed to last player
    let priority = app.world.resource::<PrioritySystem>();
    assert_eq!(priority.has_priority, player4);
    
    // Last player passes
    app.world.send_event(PriorityPassedEvent { player: player4 });
    app.update();
    
    // All players passed, should move to next phase
    let priority = app.world.resource::<PrioritySystem>();
    assert!(priority.all_players_passed);
}
}

Test: Priority After Casting a Spell

#![allow(unused)]
fn main() {
#[test]
fn test_priority_after_spell() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (handle_priority, handle_spell_cast));
       
    // Create a multiplayer game with 4 players
    let player1 = app.world.spawn(Player { id: 1 }).id();
    let player2 = app.world.spawn(Player { id: 2 }).id();
    let player3 = app.world.spawn(Player { id: 3 }).id();
    let player4 = app.world.spawn(Player { id: 4 }).id();
    
    // Set up turn order
    app.insert_resource(TurnOrder {
        players: vec![player1, player2, player3, player4],
        current_index: 0,
    });
    
    app.insert_resource(TurnManager {
        current_phase: Phase::PreCombatMain,
        active_player: player1,
    });
    
    app.insert_resource(PrioritySystem {
        has_priority: player1,
        stack_is_empty: true,
        all_players_passed: false,
    });
    
    // Create a spell
    let spell = app.world.spawn((
        Card { name: "Instant Spell".to_string() },
        Spell,
        Owner { player: player1 },
    )).id();
    
    // Player 1 casts a spell
    app.world.send_event(SpellCastEvent { 
        caster: player1,
        spell: spell,
    });
    app.update();
    
    // Verify spell is on the stack
    let stack = app.world.resource::<Stack>();
    assert!(!stack.is_empty());
    
    // Stack is not empty and priority passed to active player again
    let priority = app.world.resource::<PrioritySystem>();
    assert_eq!(priority.has_priority, player1);
    assert!(!priority.stack_is_empty);
    
    // All players need to pass again for spell to resolve
    app.world.send_event(PriorityPassedEvent { player: player1 });
    app.update();
    app.world.send_event(PriorityPassedEvent { player: player2 });
    app.update();
    app.world.send_event(PriorityPassedEvent { player: player3 });
    app.update();
    app.world.send_event(PriorityPassedEvent { player: player4 });
    app.update();
    
    // Spell should resolve and priority goes back to active player
    let stack = app.world.resource::<Stack>();
    assert!(stack.is_empty());
    
    let priority = app.world.resource::<PrioritySystem>();
    assert_eq!(priority.has_priority, player1);
}
}

These test cases ensure the Commander game engine properly handles multiplayer turn structure, including phase management, turn order, and priority passing in multiplayer scenarios.

Commander-Specific Stack and Priority

Overview

This section covers the Commander-specific aspects of the stack and priority system in Rummage. For core stack and priority mechanics that apply to all formats, see the MTG Core Stack and Priority documentation.

Commander Stack Extensions

The Commander format extends the basic MTG stack and priority system with these key features:

1. Multiplayer Priority - Modified priority passing for games with 3+ players
2. Commander Casting - Special handling for casting commanders from the command zone
3. Political Interaction - Support for verbal agreements and diplomacy during priority windows

Contents

• Stack Implementation - Commander-specific stack extensions
• Priority Passing - Priority in multiplayer Commander games
• Special Timing Rules - Format-specific timing considerations

Key Commander Stack Features

Multiplayer Priority Flow

In multiplayer Commander games, priority passes in turn order starting with the active player:

#![allow(unused)]
fn main() {
pub fn get_next_priority_player(
    current_player: Entity,
    player_order: &Vec<Entity>,
) -> Entity {
    let current_index = player_order.iter().position(|&p| p == current_player).unwrap();
    let next_index = (current_index + 1) % player_order.len();
    player_order[next_index]
}
}

This system handles priority passing among all players in the game, ensuring each player has an opportunity to respond before a spell or ability resolves.

Commander Casting from Command Zone

When a player casts their commander from the command zone, special rules apply:

• The commander tax increases the cost by {2} for each previous cast from the command zone
• The commander moves from the command zone to the stack
• All players have an opportunity to respond before it resolves

Political Considerations

While not encoded in the rules, the Commander format involves political dynamics:

• Players may make deals about actions they'll take when they have priority
• Verbal agreements can influence who players target with spells or attacks
• Priority windows are important moments for diplomatic negotiation

Command Zone Integration

The stack system integrates closely with the Command Zone implementation to handle:

• Moving commanders between the command zone and the stack
• Tracking commander tax for casting costs
• Handling commanders with alternative casting methods

Related Systems

Commander stack and priority interact with several other systems:

• Game Zones - Especially the Command Zone
• Player Mechanics - For managing player turns and actions
• Special Rules - For Commander-specific abilities

Testing

Comprehensive tests verify correct handling of stack and priority in multiplayer Commander games, with special attention to:

• Correct priority order in multiplayer scenarios
• Commander tax application when casting from the command zone
• Interaction of simultaneous triggered abilities from multiple players

Next: Stack Implementation

Stack Implementation

Priority Passing

Special Timing Rules

Stack and Priority Tests

This section contains tests related to the stack and priority system in the Commander format.

Stack Resolution Tests

The Stack Resolution Tests validate the proper functioning of the stack in various scenarios, including:

• Proper ordering of spells and abilities on the stack
• Resolution of the stack in LIFO (Last In, First Out) order
• Handling of counterspells and other stack-modifying effects
• Split second and other special timing rules
• Multiplayer priority passing
• Stack interactions with state-based actions

These tests ensure that the stack and priority system conform to Magic: The Gathering rules and behave correctly within the multiplayer context of the Commander format.

Stack Resolution Tests

Overview

This document outlines test cases for the stack system in Commander format. These tests ensure that the stack operates correctly, spells and abilities resolve in the right order, and that priority passing works as expected in this multiplayer format.

Test Case: Basic Stack Resolution

Test: Last In, First Out Resolution Order

#![allow(unused)]
fn main() {
#[test]
fn test_lifo_resolution() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (handle_stack_resolution, update_game_state));
       
    // Create player
    let player = app.world.spawn(Player {}).id();
    
    // Create spells for the stack
    let spell1 = app.world.spawn((
        Card { name: "First Spell".to_string() },
        Spell,
        StackPosition(0),
    )).id();
    
    let spell2 = app.world.spawn((
        Card { name: "Second Spell".to_string() },
        Spell,
        StackPosition(1),
    )).id();
    
    let spell3 = app.world.spawn((
        Card { name: "Third Spell".to_string() },
        Spell,
        StackPosition(2),
    )).id();
    
    // Set up stack with spells in order
    app.insert_resource(Stack {
        items: vec![spell1, spell2, spell3],
    });
    
    // Track resolution order
    app.insert_resource(ResolutionOrder { items: Vec::new() });
    
    // All players pass priority
    app.insert_resource(PrioritySystem {
        has_priority: player,
        stack_is_empty: false,
        all_players_passed: true,
    });
    
    // Resolve stack
    app.update();
    
    // Verify resolution happened in LIFO order
    let resolution_order = app.world.resource::<ResolutionOrder>();
    assert_eq!(resolution_order.items, vec![spell3, spell2, spell1]);
}
}

Test Case: Interrupting Stack Resolution

Test: Adding to the Stack During Resolution

#![allow(unused)]
fn main() {
#[test]
fn test_stack_interruption() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (handle_stack_resolution, handle_triggered_abilities));
       
    // Create player
    let player = app.world.spawn(Player {}).id();
    
    // Create an ability that will trigger when a spell resolves
    let permanent = app.world.spawn((
        Card { name: "Ability Source".to_string() },
        Permanent,
        TriggeredAbility {
            trigger: Trigger::SpellResolution,
            ability: AbilityType::CreateEffect,
        },
        Controller { player },
    )).id();
    
    // Create spells for the stack
    let spell1 = app.world.spawn((
        Card { name: "First Spell".to_string() },
        Spell,
        StackPosition(0),
    )).id();
    
    let spell2 = app.world.spawn((
        Card { name: "Second Spell".to_string() },
        Spell,
        StackPosition(1),
    )).id();
    
    // Set up stack with spells
    app.insert_resource(Stack {
        items: vec![spell1, spell2],
    });
    
    // All players pass priority
    app.insert_resource(PrioritySystem {
        has_priority: player,
        stack_is_empty: false,
        all_players_passed: true,
    });
    
    // Partially resolve stack (just the top spell)
    app.update();
    
    // Verify the triggered ability was put on the stack
    let stack = app.world.resource::<Stack>();
    assert_eq!(stack.items.len(), 2); // Original spell1 + new triggered ability
    
    // Check that the new ability is at the top of the stack
    let top_item = stack.items.last().unwrap();
    assert!(app.world.get::<TriggeredAbility>(*top_item).is_some());
}
}

Test Case: Priority Passing in Multiplayer

Test: Full Round of Priority After Spell Cast

#![allow(unused)]
fn main() {
#[test]
fn test_multiplayer_priority() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (handle_priority, handle_spell_cast));
       
    // Create multiple players
    let player1 = app.world.spawn(Player { id: 1 }).id();
    let player2 = app.world.spawn(Player { id: 2 }).id();
    let player3 = app.world.spawn(Player { id: 3 }).id();
    let player4 = app.world.spawn(Player { id: 4 }).id();
    
    // Set up turn order
    app.insert_resource(TurnOrder {
        players: vec![player1, player2, player3, player4],
        current_index: 0,
    });
    
    app.insert_resource(TurnManager {
        current_phase: Phase::PreCombatMain,
        active_player: player1,
    });
    
    // Create a spell
    let spell = app.world.spawn((
        Card { name: "Test Spell".to_string() },
        Spell,
        Owner { player: player1 },
    )).id();
    
    // Player 1 has priority initially
    app.insert_resource(PrioritySystem {
        has_priority: player1,
        stack_is_empty: true,
        all_players_passed: false,
    });
    
    // Player 1 casts a spell
    app.world.send_event(SpellCastEvent {
        caster: player1,
        spell: spell,
    });
    app.update();
    
    // Verify spell is on stack
    let stack = app.world.resource::<Stack>();
    assert_eq!(stack.items.len(), 1);
    assert_eq!(stack.items[0], spell);
    
    // Verify priority returned to active player
    let priority = app.world.resource::<PrioritySystem>();
    assert_eq!(priority.has_priority, player1);
    
    // Player 1 passes priority
    app.world.send_event(PriorityPassedEvent { player: player1 });
    app.update();
    
    // Priority passes to player 2
    let priority = app.world.resource::<PrioritySystem>();
    assert_eq!(priority.has_priority, player2);
    
    // Player 2 has opportunity to respond
    let response_spell = app.world.spawn((
        Card { name: "Response Spell".to_string() },
        Spell,
        Owner { player: player2 },
    )).id();
    
    // Player 2 casts a response
    app.world.send_event(SpellCastEvent {
        caster: player2,
        spell: response_spell,
    });
    app.update();
    
    // Verify both spells are on stack with response on top
    let stack = app.world.resource::<Stack>();
    assert_eq!(stack.items.len(), 2);
    assert_eq!(stack.items[1], response_spell);
    
    // Verify priority returned to player 2
    let priority = app.world.resource::<PrioritySystem>();
    assert_eq!(priority.has_priority, player2);
    
    // All players need to pass again for anything to resolve
    app.world.send_event(PriorityPassedEvent { player: player2 });
    app.update();
    app.world.send_event(PriorityPassedEvent { player: player3 });
    app.update();
    app.world.send_event(PriorityPassedEvent { player: player4 });
    app.update();
    app.world.send_event(PriorityPassedEvent { player: player1 });
    app.update();
    
    // Top spell should resolve
    app.update();
    
    // Verify response spell resolved
    let stack = app.world.resource::<Stack>();
    assert_eq!(stack.items.len(), 1);
    assert_eq!(stack.items[0], spell);
}
}

Test Case: Split Second and Interrupts

Test: Split Second Prevents Further Responses

#![allow(unused)]
fn main() {
#[test]
fn test_split_second() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (handle_priority, handle_spell_cast, validate_spell_cast));
       
    // Create players
    let player1 = app.world.spawn(Player { id: 1 }).id();
    let player2 = app.world.spawn(Player { id: 2 }).id();
    
    // Set up turn order
    app.insert_resource(TurnOrder {
        players: vec![player1, player2],
        current_index: 0,
    });
    
    app.insert_resource(TurnManager {
        current_phase: Phase::PreCombatMain,
        active_player: player1,
    });
    
    // Create a split second spell
    let split_second_spell = app.world.spawn((
        Card { name: "Split Second Spell".to_string() },
        Spell,
        SplitSecond,
        Owner { player: player1 },
    )).id();
    
    // Player 1 has priority initially
    app.insert_resource(PrioritySystem {
        has_priority: player1,
        stack_is_empty: true,
        all_players_passed: false,
    });
    
    // Player 1 casts split second spell
    app.world.send_event(SpellCastEvent {
        caster: player1,
        spell: split_second_spell,
    });
    app.update();
    
    // Verify split second spell is on stack
    let stack = app.world.resource::<Stack>();
    assert_eq!(stack.items.len(), 1);
    assert_eq!(stack.items[0], split_second_spell);
    
    // Create a response spell
    let response_spell = app.world.spawn((
        Card { name: "Response Spell".to_string() },
        Spell,
        Owner { player: player2 },
    )).id();
    
    // Priority passes to player 2
    app.world.resource_mut::<PrioritySystem>().has_priority = player2;
    
    // Player 2 attempts to cast a response
    app.world.send_event(SpellCastEvent {
        caster: player2,
        spell: response_spell,
    });
    app.update();
    
    // Verify response spell was prevented from being cast
    let stack = app.world.resource::<Stack>();
    assert_eq!(stack.items.len(), 1); // Still only the split second spell
    
    // Only mana abilities and special actions can be taken
    let mana_ability = app.world.spawn((
        Card { name: "Mana Source".to_string() },
        ManaAbility,
        Owner { player: player2 },
    )).id();
    
    // Player 2 activates a mana ability
    app.world.send_event(ActivateManaAbilityEvent {
        player: player2,
        ability: mana_ability,
    });
    app.update();
    
    // Verify mana ability was allowed
    assert!(app.world.resource::<Events<ManaProducedEvent>>().is_empty() == false);
}
}

Test Case: Counterspells and Responses

Test: Counterspell on the Stack

#![allow(unused)]
fn main() {
#[test]
fn test_counterspell() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (handle_stack_resolution, handle_spell_cast, handle_counterspell));
       
    // Create player
    let player1 = app.world.spawn(Player { id: 1 }).id();
    let player2 = app.world.spawn(Player { id: 2 }).id();
    
    // Create a target spell
    let target_spell = app.world.spawn((
        Card { name: "Target Spell".to_string() },
        Spell,
        Owner { player: player1 },
    )).id();
    
    // Create a counterspell
    let counterspell = app.world.spawn((
        Card { name: "Counterspell".to_string() },
        Spell,
        CounterspellEffect,
        Owner { player: player2 },
    )).id();
    
    // Put target spell on stack
    app.insert_resource(Stack {
        items: vec![target_spell],
    });
    
    // Player 2 casts counterspell targeting the spell
    app.world.send_event(SpellCastEvent {
        caster: player2,
        spell: counterspell,
    });
    
    // Set up targets for counterspell
    app.world.spawn((
        Target {
            source: counterspell,
            targets: vec![TargetInfo {
                entity: target_spell,
                target_type: TargetType::Spell,
            }],
        },
    ));
    app.update();
    
    // Verify both spells on stack with counterspell on top
    let stack = app.world.resource::<Stack>();
    assert_eq!(stack.items.len(), 2);
    assert_eq!(stack.items[1], counterspell);
    
    // All players pass priority
    app.insert_resource(PrioritySystem {
        has_priority: player1,
        stack_is_empty: false,
        all_players_passed: true,
    });
    
    // Resolve counterspell
    app.update();
    
    // Verify target spell was countered and removed from stack
    let stack = app.world.resource::<Stack>();
    assert!(stack.items.is_empty());
    
    // Verify target spell moved to graveyard
    assert_eq!(app.world.get::<Zone>(target_spell).unwrap(), &Zone::Graveyard);
}
}

Test: Uncounterable Spell

#![allow(unused)]
fn main() {
#[test]
fn test_uncounterable_spell() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (handle_stack_resolution, handle_spell_cast, handle_counterspell));
       
    // Create player
    let player1 = app.world.spawn(Player { id: 1 }).id();
    let player2 = app.world.spawn(Player { id: 2 }).id();
    
    // Create an uncounterable spell
    let uncounterable_spell = app.world.spawn((
        Card { name: "Uncounterable Spell".to_string() },
        Spell,
        CannotBeCountered,
        Owner { player: player1 },
    )).id();
    
    // Create a counterspell
    let counterspell = app.world.spawn((
        Card { name: "Counterspell".to_string() },
        Spell,
        CounterspellEffect,
        Owner { player: player2 },
    )).id();
    
    // Put uncounterable spell on stack
    app.insert_resource(Stack {
        items: vec![uncounterable_spell],
    });
    
    // Player 2 casts counterspell targeting the spell
    app.world.send_event(SpellCastEvent {
        caster: player2,
        spell: counterspell,
    });
    
    // Set up targets for counterspell
    app.world.spawn((
        Target {
            source: counterspell,
            targets: vec![TargetInfo {
                entity: uncounterable_spell,
                target_type: TargetType::Spell,
            }],
        },
    ));
    app.update();
    
    // Verify both spells on stack
    let stack = app.world.resource::<Stack>();
    assert_eq!(stack.items.len(), 2);
    
    // All players pass priority
    app.insert_resource(PrioritySystem {
        has_priority: player1,
        stack_is_empty: false,
        all_players_passed: true,
    });
    
    // Resolve counterspell
    app.update();
    
    // Verify uncounterable spell remains on stack
    let stack = app.world.resource::<Stack>();
    assert_eq!(stack.items.len(), 1);
    assert_eq!(stack.items[0], uncounterable_spell);
    
    // Verify counterspell went to graveyard
    assert_eq!(app.world.get::<Zone>(counterspell).unwrap(), &Zone::Graveyard);
}
}

Test Case: Triggered Abilities and The Stack

Test: Multiple Triggered Abilities Order

#![allow(unused)]
fn main() {
#[test]
fn test_multiple_triggers() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (handle_triggered_abilities, order_triggered_abilities));
       
    // Create players
    let player1 = app.world.spawn(Player { id: 1 }).id();
    let player2 = app.world.spawn(Player { id: 2 }).id();
    
    // Turn order
    app.insert_resource(TurnOrder {
        players: vec![player1, player2],
        current_index: 0,
    });
    
    app.insert_resource(TurnManager {
        current_phase: Phase::Beginning(BeginningPhaseStep::Upkeep),
        active_player: player1,
    });
    
    // Create permanents with upkeep triggers for both players
    let permanent1 = app.world.spawn((
        Card { name: "Permanent 1".to_string() },
        Permanent,
        TriggeredAbility {
            trigger: Trigger::Upkeep(TriggerController::ActivePlayer),
            ability: AbilityType::DrawCard,
        },
        Controller { player: player1 },
    )).id();
    
    let permanent2 = app.world.spawn((
        Card { name: "Permanent 2".to_string() },
        Permanent,
        TriggeredAbility {
            trigger: Trigger::Upkeep(TriggerController::ActivePlayer),
            ability: AbilityType::GainLife(1),
        },
        Controller { player: player1 },
    )).id();
    
    let permanent3 = app.world.spawn((
        Card { name: "Permanent 3".to_string() },
        Permanent,
        TriggeredAbility {
            trigger: Trigger::Upkeep(TriggerController::ActivePlayer),
            ability: AbilityType::LoseLife(1),
        },
        Controller { player: player2 },
    )).id();
    
    // Trigger abilities
    app.world.send_event(PhaseChangedEvent {
        new_phase: Phase::Beginning(BeginningPhaseStep::Upkeep),
    });
    app.update();
    
    // Verify triggers were put on stack
    let stack = app.world.resource::<Stack>();
    assert_eq!(stack.items.len(), 3);
    
    // Verify triggers from active player go on stack in APNAP order
    // (Active Player, Non-Active Player)
    let stack_items = &stack.items;
    
    // Active player's abilities should be first (in controller's choice order)
    let first_two_controllers: Vec<Entity> = stack_items.iter()
        .take(2)
        .map(|e| app.world.get::<Controller>(*e).unwrap().player)
        .collect();
    
    // The first two should belong to player1 (active player)
    assert_eq!(first_two_controllers, vec![player1, player1]);
    
    // The last ability should belong to player2
    let last_controller = app.world.get::<Controller>(stack_items[2]).unwrap().player;
    assert_eq!(last_controller, player2);
}
}

Test Case: Stack and State-Based Actions

Test: State-Based Actions Between Stack Resolutions

#![allow(unused)]
fn main() {
#[test]
fn test_state_based_actions_and_stack() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (handle_stack_resolution, handle_state_based_actions));
       
    // Create player and creature
    let player = app.world.spawn(Player {}).id();
    
    let creature = app.world.spawn((
        Card { name: "Creature".to_string() },
        Creature { power: 3, toughness: 3 },
        Health { current: 3, maximum: 3 },
        Zone::Battlefield,
        Owner { player },
    )).id();
    
    // Create damage spell
    let damage_spell = app.world.spawn((
        Card { name: "Lightning Bolt".to_string() },
        Spell,
        DamageEffect { amount: 3 },
        Owner { player },
    )).id();
    
    // Create spell target
    app.world.spawn((
        Target {
            source: damage_spell,
            targets: vec![TargetInfo {
                entity: creature,
                target_type: TargetType::Creature,
            }],
        },
    ));
    
    // Create heal spell that will be cast in response
    let heal_spell = app.world.spawn((
        Card { name: "Healing Touch".to_string() },
        Spell,
        HealEffect { amount: 3 },
        Owner { player },
    )).id();
    
    // Create heal target
    app.world.spawn((
        Target {
            source: heal_spell,
            targets: vec![TargetInfo {
                entity: creature,
                target_type: TargetType::Creature,
            }],
        },
    ));
    
    // Put spells on stack in order (heal on top, will resolve first)
    app.insert_resource(Stack {
        items: vec![damage_spell, heal_spell],
    });
    
    // Setup priority for resolution
    app.insert_resource(PrioritySystem {
        has_priority: player,
        stack_is_empty: false,
        all_players_passed: true,
    });
    
    // Resolve heal spell
    app.update();
    
    // Verify creature healed to full
    let health = app.world.get::<Health>(creature).unwrap();
    assert_eq!(health.current, 3);
    
    // Still one spell on stack
    let stack = app.world.resource::<Stack>();
    assert_eq!(stack.items.len(), 1);
    
    // Resolve damage spell
    app.update();
    
    // Verify creature took damage
    let health = app.world.get::<Health>(creature).unwrap();
    assert_eq!(health.current, 0);
    
    // Verify stack is empty
    let stack = app.world.resource::<Stack>();
    assert!(stack.items.is_empty());
    
    // Apply state-based actions check
    app.update();
    
    // Verify creature died due to state-based actions
    assert_eq!(app.world.get::<Zone>(creature).unwrap(), &Zone::Graveyard);
}
}

These test cases ensure the stack resolution system functions correctly, handling priority passing, triggered abilities, counterspells, and state-based actions in accordance with Commander's rules.

Commander-Specific Combat Mechanics

Overview

This section covers the Commander-specific combat mechanics in the Rummage game engine. For core combat mechanics that apply to all formats, see the MTG Core Combat documentation.

Commander Combat Extensions

Commander extends the basic MTG combat system with these key mechanics:

1. Commander Damage - A player who has been dealt 21 or more combat damage by the same commander loses the game
2. Multiplayer Combat - Special considerations for attacking and blocking in a multiplayer environment
3. Commander-specific Combat Abilities - Handling abilities that interact with commander status

Contents

• Commander Damage - Implementation of the 21-damage loss condition
• Multiplayer Combat - Special rules for combat with multiple players
• Combat Verification - Validation of combat decisions in multiplayer scenarios
• Combat Abilities - Implementation of commander-specific combat abilities

Key Commander Combat Features

Commander Damage Tracking

The system tracks commander damage separately from regular damage:

#![allow(unused)]
fn main() {
#[derive(Component)]
pub struct CommanderDamageTracker {
    // Maps commander entity -> damage dealt to player
    pub damage_taken: HashMap<Entity, u32>,
}
}

When a player takes 21 or more combat damage from the same commander, they lose the game regardless of their life total.

Multiplayer Combat Dynamics

Commander's multiplayer format introduces unique combat dynamics:

• Players can attack any opponent, not just the player to their left/right
• Political considerations affect attack and block decisions
• Players can make deals regarding combat (though these aren't enforced by the game rules)

Combat in Multiplayer Politics

Combat is central to the political dynamics of Commander:

• Attacks signal aggression and can lead to retaliation
• Defending other players can forge temporary alliances
• Commander damage creates an additional threat vector beyond life totals

Related Systems

Commander combat interacts with several other systems:

• Player Mechanics - For life total and commander damage tracking
• Game Mechanics - For state-based actions that check commander damage thresholds
• Special Rules - For politics and multiplayer considerations

Testing

The tests directory contains comprehensive test cases for validating commander-specific combat mechanics, with special focus on commander damage tracking and multiplayer scenarios.

Next: Commander Damage

Combat Phases

Overview

The Combat Phase in Commander follows the standard Magic: The Gathering combat sequence, with special considerations for the multiplayer nature of the format. This document provides an overview of the combat phase structure and links to detailed implementation documentation for each step.

Combat Phase Sequence

The Combat Phase consists of five distinct steps:

1. Beginning of Combat Step - The phase begins and "at beginning of combat" triggered abilities go on the stack
2. Declare Attackers Step - The active player declares attackers and "when attacks" triggered abilities go on the stack
3. Declare Blockers Step - Each defending player declares blockers and "when blocks/blocked" triggered abilities go on the stack
4. Combat Damage Step - Combat damage is assigned and dealt, and "when deals damage" triggered abilities go on the stack
5. End of Combat Step - The phase ends and "at end of combat" triggered abilities go on the stack

Implementation Architecture

Combat phases are implemented using a combination of phase-specific systems and a shared combat state:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum CombatStep {
    Beginning,
    DeclareAttackers,
    DeclareBlockers,
    FirstStrike,
    CombatDamage,
    End,
}

// Systems for handling different combat steps
pub fn beginning_of_combat_system(
    mut combat_system: ResMut<CombatSystem>,
    turn_manager: Res<TurnManager>,
    mut commands: Commands,
    // Other system parameters
) {
    // Implementation
}

pub fn declare_attackers_system(
    mut combat_system: ResMut<CombatSystem>,
    turn_manager: Res<TurnManager>,
    // Other system parameters
) {
    // Implementation
}

// And so on for other combat steps
}

Detailed Phase Documentation

Each combat step has its own specialized implementation with unique rules and edge cases:

• Beginning of Combat - Initialization of combat and "beginning of combat" triggers
• Declare Attackers - Attack declaration, restrictions, and requirements
• Declare Blockers - Block declaration, restrictions, and requirements
• Combat Damage - Damage assignment, ordering, and resolution
• End of Combat - Combat cleanup and "end of combat" triggers

Combat Phase Transitions

The transition between combat steps is managed by the TurnManager, which ensures that:

1. Each step is processed in the correct order
2. Priority is passed to all players in turn order during each step
3. The stack is emptied before proceeding to the next step
4. Any special effects that modify the combat phase flow are properly handled

Integration with Turn Structure

The combat phase is integrated into the overall turn structure via the TurnManager:

#![allow(unused)]
fn main() {
impl TurnManager {
    pub fn advance_phase(&mut self) -> Result<Phase, TurnError> {
        self.current_phase = match self.current_phase {
            // Other phases...
            Phase::Combat(CombatStep::Beginning) => Phase::Combat(CombatStep::DeclareAttackers),
            Phase::Combat(CombatStep::DeclareAttackers) => Phase::Combat(CombatStep::DeclareBlockers),
            Phase::Combat(CombatStep::DeclareBlockers) => {
                if self.has_first_strike_creatures() {
                    Phase::Combat(CombatStep::FirstStrike)
                } else {
                    Phase::Combat(CombatStep::CombatDamage)
                }
            },
            Phase::Combat(CombatStep::FirstStrike) => Phase::Combat(CombatStep::CombatDamage),
            Phase::Combat(CombatStep::CombatDamage) => Phase::Combat(CombatStep::End),
            Phase::Combat(CombatStep::End) => Phase::Postcombat(PostcombatStep::Main),
            // Other phases...
        };
        
        // Further implementation
    }
}
}

Commander Damage

Overview

Commander Damage is a fundamental aspect of the Commander format. Any player who has taken 21 or more combat damage from a single commander loses the game. This unique rule adds an additional win condition and strategic layer to the multiplayer format. The implementation must accurately track, accumulate, and verify commander damage while handling edge cases like commander ownership changes or damage redirection effects.

Random Effects and Commander Damage

Commander damage can be affected by various random effects, such as:

• Coin flips that double damage or prevent damage
• Dice rolls that modify combat damage
• Random damage redirection

For test cases involving commander damage and random mechanics, see the Random Mechanics documentation.

Core Implementation

#![allow(unused)]
fn main() {
// Player component with commander damage tracking
#[derive(Component)]
pub struct Player {
    pub life_total: i32,
    pub commander_damage: HashMap<Entity, u32>,
    // Other player state fields omitted
}

// System to process commander damage
pub fn commander_damage_system(
    mut player_query: Query<(Entity, &mut Player)>,
    combat_system: Res<CombatSystem>,
    commanders: Query<Entity, With<Commander>>,
    mut game_events: EventWriter<GameEvent>,
) {
    // Collect any combat damage dealt by commanders
    let commander_damage_events = combat_system.combat_history
        .iter()
        .filter_map(|event| {
            if let CombatEvent::DamageDealt { source, target, amount, is_commander_damage } = event {
                if *is_commander_damage && commanders.contains(*source) {
                    return Some((*source, *target, *amount));
                }
            }
            None
        })
        .collect::<Vec<_>>();
    
    // Process the commander damage
    for (commander, target, amount) in commander_damage_events {
        for (player_entity, mut player) in player_query.iter_mut() {
            if player_entity == target {
                // Apply commander damage
                let previous_damage = player.commander_damage.get(&commander).copied().unwrap_or(0);
                let total_damage = previous_damage + amount;
                player.commander_damage.insert(commander, total_damage);
                
                // Check for commander damage loss condition
                if total_damage >= 21 {
                    game_events.send(GameEvent::PlayerLost {
                        player: player_entity,
                        reason: LossReason::CommanderDamage(commander),
                    });
                }
            }
        }
    }
}
}

Damage Application System

The combat damage system needs special handling for commander damage:

#![allow(unused)]
fn main() {
pub fn apply_combat_damage_system(
    mut combat_system: ResMut<CombatSystem>,
    turn_manager: Res<TurnManager>,
    mut creature_query: Query<(Entity, &mut Creature, Option<&Commander>)>,
    mut player_query: Query<(Entity, &mut Player)>,
    mut planeswalker_query: Query<(Entity, &mut Planeswalker)>,
    mut game_events: EventWriter<GameEvent>,
) {
    // Only run during combat damage step
    if turn_manager.current_phase != Phase::Combat(CombatStep::CombatDamage) {
        return;
    }
    
    // Process each attacker that wasn't blocked
    for (attacker, attack_data) in combat_system.attackers.iter() {
        // Skip attackers that were blocked
        if combat_system.blockers.values().any(|block_data| 
            block_data.blocked_attackers.contains(attacker)) {
            continue;
        }
        
        // Get attacker data
        if let Ok((_, creature, commander)) = creature_query.get(*attacker) {
            let power = creature.power;
            let is_commander = commander.is_some();
            
            // Apply damage to defender
            let defender = attack_data.defender;
            
            // Check if defender is a player
            if let Ok((player_entity, mut player)) = player_query.get_mut(defender) {
                // Apply damage to player
                player.life_total -= power as i32;
                
                // Record damage event
                combat_system.combat_history.push_back(CombatEvent::DamageDealt {
                    source: *attacker,
                    target: player_entity,
                    amount: power,
                    is_commander_damage: is_commander,
                });
                
                // Check if player lost due to life total
                if player.life_total <= 0 {
                    game_events.send(GameEvent::PlayerLost {
                        player: player_entity,
                        reason: LossReason::ZeroLife,
                    });
                }
            }
            // Check if defender is a planeswalker
            else if let Ok((planeswalker_entity, mut planeswalker)) = planeswalker_query.get_mut(defender) {
                // Apply damage to planeswalker
                planeswalker.loyalty -= power as i32;
                
                // Record damage event
                combat_system.combat_history.push_back(CombatEvent::DamageDealt {
                    source: *attacker,
                    target: planeswalker_entity,
                    amount: power,
                    is_commander_damage: false, // Commander damage only applies to players
                });
                
                // Check if planeswalker was destroyed
                if planeswalker.loyalty <= 0 {
                    game_events.send(GameEvent::PlaneswalkerDestroyed {
                        planeswalker: planeswalker_entity,
                    });
                }
            }
        }
    }
    
    // Similar processing for blocked attackers
    // Implementation details omitted for brevity
}
}

Handling Commander Identity Changes

When a commander changes identity (e.g., due to effects like Sakashima of a Thousand Faces), the damage tracking needs to be maintained:

#![allow(unused)]
fn main() {
pub fn handle_commander_identity_change(
    mut commands: Commands,
    mut combat_system: ResMut<CombatSystem>,
    mut player_query: Query<&mut Player>,
    commander_query: Query<(Entity, &Commander, &OriginalEntity)>,
) {
    for (current_entity, commander, original) in commander_query.iter() {
        // If the commander has a different original entity
        if current_entity != original.0 {
            // Update all players' commander damage tracking
            for mut player in player_query.iter_mut() {
                if let Some(damage) = player.commander_damage.remove(&original.0) {
                    player.commander_damage.insert(current_entity, damage);
                }
            }
            
            // Update combat system tracking if needed
            for attack_data in combat_system.attackers.values_mut() {
                if attack_data.attacker == original.0 {
                    attack_data.attacker = current_entity;
                    attack_data.is_commander = true;
                }
            }
        }
    }
}
}

UI Representation

The commander damage tracking needs to be visually represented to players:

#![allow(unused)]
fn main() {
pub fn update_commander_damage_ui_system(
    player_query: Query<(Entity, &Player)>,
    commander_query: Query<(Entity, &Commander, &Card)>,
    mut ui_state: ResMut<UiState>,
) {
    // Update UI representation of commander damage for each player
    for (player_entity, player) in player_query.iter() {
        let mut commander_damage_display = Vec::new();
        
        for (commander_entity, _, card) in commander_query.iter() {
            let damage = player.commander_damage.get(&commander_entity).copied().unwrap_or(0);
            
            commander_damage_display.push(CommanderDamageDisplay {
                commander_entity,
                commander_name: card.name.clone(),
                damage,
                progress: (damage as f32) / 21.0, // For progress bar visualization
                lethal: damage >= 21,
            });
        }
        
        // Sort by damage amount (highest first)
        commander_damage_display.sort_by(|a, b| b.damage.cmp(&a.damage));
        
        // Update UI state
        ui_state.player_commander_damage.insert(player_entity, commander_damage_display);
    }
}
}

Edge Cases

Damage Redirection

Some effects can redirect damage, which needs special handling for commander damage:

#![allow(unused)]
fn main() {
pub fn handle_damage_redirection(
    mut combat_system: ResMut<CombatSystem>,
    redirection_effects: Query<(Entity, &DamageRedirection)>,
) {
    // Check for redirection effects when processing damage events
    let mut redirected_damage = Vec::new();
    
    for event in combat_system.pending_combat_events.iter() {
        if let CombatEvent::DamageDealt { source, target, amount, is_commander_damage } = event {
            // Check for redirection effects affecting this target
            for (effect_entity, redirection) in redirection_effects.iter() {
                if redirection.target == *target {
                    // Redirect the damage
                    redirected_damage.push(CombatEvent::DamageDealt {
                        source: *source,
                        target: redirection.redirect_to,
                        amount: *amount,
                        // Important: Commander damage is preserved ONLY if damage source doesn't change
                        is_commander_damage: *is_commander_damage && redirection.preserve_source,
                    });
                }
            }
        }
    }
    
    // Add redirected damage events to combat history
    for event in redirected_damage {
        combat_system.combat_history.push_back(event);
    }
}
}

Change of Control

When a commander changes control, the damage tracking needs to be maintained:

#![allow(unused)]
fn main() {
pub fn handle_commander_control_change(
    mut player_query: Query<&mut Player>,
    mut control_change_events: EventReader<ControlChangeEvent>,
    commander_query: Query<Entity, With<Commander>>,
) {
    // Process control change events
    for event in control_change_events.iter() {
        // Only care about commanders changing control
        if commander_query.contains(event.entity) {
            // Commander damage is tracked by entity, so no changes needed to players' tracking
            // The entity's controller changes but damage tracking by entity ID remains the same
            
            // Log the event for record-keeping
            info!("Commander {:?} changed control from {:?} to {:?}", 
                  event.entity, event.old_controller, event.new_controller);
        }
    }
}
}

Double Strike and Commander Damage

Double strike creatures need special handling for commander damage:

#![allow(unused)]
fn main() {
pub fn handle_double_strike_commander_damage(
    mut combat_system: ResMut<CombatSystem>,
    creature_query: Query<(Entity, &Creature, Option<&Commander>)>,
) {
    // Get all double strike commanders
    let double_strike_commanders = creature_query.iter()
        .filter_map(|(entity, creature, commander)| {
            if commander.is_some() && creature.has_ability(Ability::Keyword(Keyword::DoubleStrike)) {
                Some(entity)
            } else {
                None
            }
        })
        .collect::<HashSet<_>>();
    
    // Special handling for double strike damage events
    let mut double_strike_events = Vec::new();
    
    for event in combat_system.combat_history.iter() {
        if let CombatEvent::DamageDealt { source, target, amount, is_commander_damage } = event {
            if *is_commander_damage && double_strike_commanders.contains(source) {
                // During first strike, we need to ensure this damage is tracked separately
                // from the regular damage that will come after
                if combat_system.active_combat_step == Some(CombatStep::FirstStrike) {
                    double_strike_events.push((*source, *target, *amount));
                }
            }
        }
    }
    
    // Record these events explicitly for commander damage tracking
    for (source, target, amount) in double_strike_events {
        info!("Tracking double strike first strike damage from commander {:?} to {:?}: {}", 
              source, target, amount);
    }
}
}

Testing Strategy

Unit Tests

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;
    
    // Test basic commander damage tracking
    #[test]
    fn test_basic_commander_damage() {
        // Setup test environment
        let mut app = App::new();
        app.add_systems(Update, commander_damage_system);
        
        // Create test entities and components
        let commander = app.world.spawn((
            Card::default(),
            Commander,
            Creature { power: 5, toughness: 5, ..Default::default() },
        )).id();
        
        let player = app.world.spawn((
            Player {
                life_total: 40,
                commander_damage: HashMap::new(),
                ..Default::default()
            },
        )).id();
        
        // Create a combat system resource with damage history
        let mut combat_system = CombatSystem::default();
        combat_system.combat_history.push_back(CombatEvent::DamageDealt {
            source: commander,
            target: player,
            amount: 5,
            is_commander_damage: true,
        });
        app.insert_resource(combat_system);
        
        // Run the system
        app.update();
        
        // Verify commander damage was tracked
        let player_entity = app.world.entity(player);
        let player_component = player_entity.get::<Player>().unwrap();
        assert_eq!(player_component.commander_damage.get(&commander), Some(&5));
    }
    
    // Test commander damage loss condition
    #[test]
    fn test_commander_damage_loss() {
        // Setup test environment with 21 commander damage
        // Test code omitted for brevity
        
        // Run the system
        app.update();
        
        // Verify loss event was sent
        let events = app.world.resource::<Events<GameEvent>>();
        let mut event_reader = EventReader::<GameEvent>::from_resource(events);
        let mut found_loss_event = false;
        
        for event in event_reader.iter() {
            if let GameEvent::PlayerLost { player: p, reason: LossReason::CommanderDamage(c) } = event {
                if *p == player && *c == commander {
                    found_loss_event = true;
                    break;
                }
            }
        }
        
        assert!(found_loss_event, "Player loss event not found");
    }
    
    // Test commander damage from multiple commanders
    #[test]
    fn test_multiple_commander_damage() {
        // Setup test with multiple commanders dealing damage
        // Test code omitted for brevity
        
        // Verify each commander's damage is tracked separately
        let player_entity = app.world.entity(player);
        let player_component = player_entity.get::<Player>().unwrap();
        assert_eq!(player_component.commander_damage.get(&commander1), Some(&15));
        assert_eq!(player_component.commander_damage.get(&commander2), Some(&10));
        
        // Verify player hasn't lost yet (no single commander has dealt 21+ damage)
        let events = app.world.resource::<Events<GameEvent>>();
        let mut event_reader = EventReader::<GameEvent>::from_resource(events);
        
        for event in event_reader.iter() {
            if let GameEvent::PlayerLost { player: _, reason: _ } = event {
                panic!("Player should not have lost yet");
            }
        }
    }
}
}

Integration Tests

#![allow(unused)]
fn main() {
#[cfg(test)]
mod integration_tests {
    use super::*;
    
    // Test commander damage through complete combat
    #[test]
    fn test_commander_damage_through_combat() {
        // Setup full game environment
        let mut app = setup_test_game();
        
        // Setup a commander attacking a player
        let commander = /* create commander entity */;
        let player = /* create player entity */;
        
        // Setup the attack
        let mut combat_system = app.world.resource_mut::<CombatSystem>();
        combat_system.attackers.insert(commander, AttackData {
            attacker: commander,
            defender: player,
            is_commander: true,
            requirements: Vec::new(),
            restrictions: Vec::new(),
        });
        
        // Advance through combat damage step
        advance_to_combat_damage(&mut app);
        
        // Run the apply damage system
        app.update();
        
        // Verify commander damage was tracked
        let player_entity = app.world.entity(player);
        let player_component = player_entity.get::<Player>().unwrap();
        
        // Assuming a 5 power commander
        assert_eq!(player_component.commander_damage.get(&commander), Some(&5));
    }
    
    // Test commander damage accumulation over multiple turns
    #[test]
    fn test_commander_damage_accumulation() {
        // Setup game and play multiple turns with commander damage
        // Test code omitted for brevity
        
        // Verify accumulated commander damage
        let player_entity = app.world.entity(player);
        let player_component = player_entity.get::<Player>().unwrap();
        assert_eq!(player_component.commander_damage.get(&commander), Some(&15));
        
        // Deal more damage to hit 21
        // Test code omitted for brevity
        
        // Verify player lost
        let events = app.world.resource::<Events<GameEvent>>();
        let mut event_reader = EventReader::<GameEvent>::from_resource(events);
        let mut found_loss_event = false;
        
        for event in event_reader.iter() {
            if let GameEvent::PlayerLost { player: p, reason: LossReason::CommanderDamage(c) } = event {
                if *p == player && *c == commander {
                    found_loss_event = true;
                    break;
                }
            }
        }
        
        assert!(found_loss_event, "Player loss event not found");
    }
    
    // Test commander damage with protection/prevention
    #[test]
    fn test_commander_damage_prevention() {
        // Setup game with protection effects
        // Test code omitted for brevity
        
        // Verify commander damage was prevented
        let player_entity = app.world.entity(player);
        let player_component = player_entity.get::<Player>().unwrap();
        assert_eq!(player_component.commander_damage.get(&commander), Some(&0));
    }
}
}

Performance Considerations

1. HashMap Efficiency: Commander damage is tracked using a HashMap which provides O(1) lookups, but care should be taken to avoid unnecessary cloning or rebuilding.

2. Event Processing: Combat damage events are processed in batches to minimize system overhead.

3. UI Updates: Commander damage UI updates should only happen when damage values change or during specific UI refresh cycles to avoid performance impact.

Implementation Recommendations

1. Persistent Storage: In a networked game, commander damage should be persisted on the server and synchronized to clients.

2. Undo Support: The system should support undoing or adjusting commander damage in case of rule disputes or corrections.

3. History Tracking: Maintain a searchable history of commander damage events for game replay and verification.

4. Visual Feedback: Provide clear visual feedback when commander damage is getting close to lethal levels (e.g., at 15+ damage).

Commander damage tracking is a critical component of the Commander format and requires careful implementation to ensure game rules are correctly enforced while maintaining good performance even in complex game states.

Multiplayer Combat

Overview

Commander is inherently a multiplayer format, which introduces unique complexities to the combat system. Unlike one-on-one matches, multiplayer combat allows a player to attack multiple opponents simultaneously and introduces political elements that affect combat decisions. This document details how the multiplayer aspects of combat are implemented, tested, and verified in our game engine.

Core Multiplayer Combat Features

Multiple Attack Targets

In Commander, the active player can declare attackers against different opponents in the same combat phase. This is implemented through the attack declaration system:

#![allow(unused)]
fn main() {
pub fn validate_multiplayer_attacks(
    combat_system: Res<CombatSystem>,
    turn_manager: Res<TurnManager>,
    player_query: Query<(Entity, &Player)>,
    mut game_events: EventWriter<GameEvent>,
) {
    let active_player = turn_manager.get_active_player();
    
    // Group attacks by defender
    let mut attacks_by_defender: HashMap<Entity, Vec<Entity>> = HashMap::new();
    
    for (attacker, attack_data) in &combat_system.attackers {
        attacks_by_defender.entry(attack_data.defender)
            .or_insert_with(Vec::new)
            .push(*attacker);
    }
    
    // Verify all defenders are opponents
    for (defender, attackers) in &attacks_by_defender {
        // Skip planeswalkers (they're handled separately)
        if !player_query.contains(*defender) {
            continue;
        }
        
        // Verify defender is not the active player
        if *defender == active_player {
            game_events.send(GameEvent::InvalidAttackTarget {
                attacker: attackers[0], // Just report one of the attackers
                defender: *defender,
                reason: "Cannot attack yourself".to_string(),
            });
        }
    }
    
    // Log all attack declarations for game history
    game_events.send(GameEvent::MultiplayerAttacksDeclared {
        active_player,
        attacks_by_defender: attacks_by_defender.clone(),
    });
}
}

Defending Player Choice

When a player is being attacked, they alone make blocking decisions for those attackers:

#![allow(unused)]
fn main() {
pub fn handle_multiplayer_blocks(
    mut combat_system: ResMut<CombatSystem>,
    turn_manager: Res<TurnManager>,
    mut block_events: EventReader<BlockDeclarationEvent>,
    player_query: Query<Entity, With<Player>>,
) {
    // Group attackers by defending player
    let mut attackers_by_defender: HashMap<Entity, Vec<Entity>> = HashMap::new();
    
    for (attacker, attack_data) in &combat_system.attackers {
        if player_query.contains(attack_data.defender) {
            attackers_by_defender.entry(attack_data.defender)
                .or_insert_with(Vec::new)
                .push(*attacker);
        }
    }
    
    // Process block declarations from each defending player
    for event in block_events.iter() {
        let BlockDeclarationEvent { player, blocker, attacker } = event;
        
        // Verify the player is declaring blocks against attackers targeting them
        if let Some(attackers) = attackers_by_defender.get(player) {
            if attackers.contains(attacker) {
                // This is a valid block declaration
                if let Some(block_data) = combat_system.blockers.get_mut(blocker) {
                    block_data.blocked_attackers.push(*attacker);
                } else {
                    combat_system.blockers.insert(*blocker, BlockData {
                        blocker: *blocker,
                        blocked_attackers: vec![*attacker],
                        requirements: Vec::new(),
                        restrictions: Vec::new(),
                    });
                }
            } else {
                // Player trying to block an attacker not targeting them
                warn!("Player {:?} tried to block attacker {:?} not targeting them", player, attacker);
            }
        }
    }
}
}

Political Game Elements

Goad Mechanic

Goad is a Commander-focused mechanic that forces creatures to attack players other than you. This is implemented as follows:

#![allow(unused)]
fn main() {
#[derive(Component)]
pub struct Goaded {
    pub source: Entity,
    pub until_end_of_turn: bool,
}

pub fn apply_goad_requirements(
    mut combat_system: ResMut<CombatSystem>,
    goaded_query: Query<(Entity, &Goaded, &Controllable)>,
    turn_manager: Res<TurnManager>,
) {
    let active_player = turn_manager.get_active_player();
    
    // Find all goaded creatures controlled by the active player
    for (entity, goaded, controllable) in goaded_query.iter() {
        if controllable.controller == active_player {
            // Add attack requirement - must attack if able
            combat_system.add_attack_requirement(entity, AttackRequirement::MustAttack);
            
            // Add attack restriction - can't attack the goad source
            combat_system.add_attack_restriction(entity, AttackRestriction::CantAttackPlayer(goaded.source));
        }
    }
}

pub fn cleanup_goad_effects(
    mut commands: Commands,
    goaded_query: Query<(Entity, &Goaded)>,
    turn_manager: Res<TurnManager>,
) {
    // Only run during end step
    if turn_manager.current_phase != Phase::Ending(EndingStep::End) {
        return;
    }
    
    // Remove goad effects that last until end of turn
    for (entity, goaded) in goaded_query.iter() {
        if goaded.until_end_of_turn {
            commands.entity(entity).remove::<Goaded>();
        }
    }
}
}

Monarch Mechanic

The monarch is another multiplayer-focused mechanic that encourages combat:

#![allow(unused)]
fn main() {
#[derive(Resource)]
pub struct Monarch(pub Option<Entity>);

pub fn monarch_attack_trigger(
    mut monarch: ResMut<Monarch>,
    combat_system: Res<CombatSystem>,
    turn_manager: Res<TurnManager>,
    mut game_events: EventWriter<GameEvent>,
) {
    // Only check at combat damage step
    if turn_manager.current_phase != Phase::Combat(CombatStep::CombatDamage) {
        return;
    }
    
    // Find players who were dealt combat damage
    let mut damaged_players = HashSet::new();
    
    for event in combat_system.combat_history.iter() {
        if let CombatEvent::DamageDealt { source, target, amount, .. } = event {
            if *amount > 0 && combat_system.attackers.contains_key(source) {
                damaged_players.insert(*target);
            }
        }
    }
    
    // Check if the monarch was dealt damage
    if let Some(current_monarch) = monarch.0 {
        if damaged_players.contains(&current_monarch) {
            // Find who dealt damage to the monarch
            for event in combat_system.combat_history.iter() {
                if let CombatEvent::DamageDealt { source, target, amount, .. } = event {
                    if *amount > 0 && *target == current_monarch && combat_system.attackers.contains_key(source) {
                        // Get the controller of the attacking creature
                        if let Some(controller) = get_controller(*source) {
                            if controller != current_monarch {
                                // Change the monarch
                                monarch.0 = Some(controller);
                                
                                game_events.send(GameEvent::MonarchChanged {
                                    old_monarch: current_monarch,
                                    new_monarch: controller,
                                    reason: "Combat damage".to_string(),
                                });
                                
                                // Only change once (first damage)
                                break;
                            }
                        }
                    }
                }
            }
        }
    }
}
}

Multiplayer Damage Tracking

In multiplayer games, damage source tracking becomes more important, especially for commander damage:

#![allow(unused)]
fn main() {
pub fn track_multiplayer_combat_damage(
    combat_system: Res<CombatSystem>,
    mut player_query: Query<(Entity, &mut Player)>,
    commander_query: Query<Entity, With<Commander>>,
    mut game_events: EventWriter<GameEvent>,
) {
    // Extract all combat damage events
    let damage_events = combat_system.combat_history
        .iter()
        .filter_map(|event| {
            if let CombatEvent::DamageDealt { source, target, amount, is_commander_damage } = event {
                Some((*source, *target, *amount, *is_commander_damage))
            } else {
                None
            }
        })
        .collect::<Vec<_>>();
    
    // Process commander damage
    for (source, target, amount, is_commander_damage) in damage_events {
        // Only process if the source is a commander and target is a player
        if is_commander_damage && commander_query.contains(source) {
            for (player_entity, mut player) in player_query.iter_mut() {
                if player_entity == target {
                    // Update commander damage tracking
                    let previous_damage = player.commander_damage.get(&source).copied().unwrap_or(0);
                    let new_damage = previous_damage + amount;
                    player.commander_damage.insert(source, new_damage);
                    
                    // Check for commander damage loss condition
                    if new_damage >= 21 {
                        game_events.send(GameEvent::PlayerLost {
                            player: player_entity,
                            reason: LossReason::CommanderDamage(source),
                        });
                    }
                }
            }
        }
    }
}
}

Teamwork Mechanics

Some Commander variants include team play, which requires special handling:

#![allow(unused)]
fn main() {
#[derive(Component)]
pub struct Team(pub u32);

pub fn validate_team_attacks(
    combat_system: Res<CombatSystem>,
    team_query: Query<(Entity, &Team)>,
    mut game_events: EventWriter<GameEvent>,
) {
    // Create team mappings
    let mut player_teams = HashMap::new();
    for (entity, team) in team_query.iter() {
        player_teams.insert(entity, team.0);
    }
    
    // Check for attacks against teammates
    for (attacker, attack_data) in &combat_system.attackers {
        if let Some(attacker_controller) = get_controller(*attacker) {
            if let (Some(attacker_team), Some(defender_team)) = (
                player_teams.get(&attacker_controller),
                player_teams.get(&attack_data.defender)
            ) {
                if attacker_team == defender_team {
                    // This is an attack against a teammate
                    game_events.send(GameEvent::TeamAttack {
                        attacker: *attacker,
                        defender: attack_data.defender,
                        team: *attacker_team,
                    });
                }
            }
        }
    }
}
}

Multiplayer Edge Cases

Player Elimination During Combat

If a player is eliminated during combat, any attackers targeting them need to be handled:

#![allow(unused)]
fn main() {
pub fn handle_player_elimination_during_combat(
    mut combat_system: ResMut<CombatSystem>,
    mut player_elimination_events: EventReader<PlayerEliminatedEvent>,
    mut commands: Commands,
) {
    for event in player_elimination_events.iter() {
        let eliminated_player = event.player;
        
        // Remove any attackers targeting the eliminated player
        let attackers_to_remove: Vec<Entity> = combat_system.attackers
            .iter()
            .filter_map(|(attacker, attack_data)| {
                if attack_data.defender == eliminated_player {
                    Some(*attacker)
                } else {
                    None
                }
            })
            .collect();
        
        for attacker in attackers_to_remove {
            combat_system.attackers.remove(&attacker);
            
            // Update creature component to no longer be attacking
            if let Some(mut creature) = commands.get_entity(attacker) {
                creature.insert(Creature {
                    attacking: None,
                    // Other fields preserved...
                    ..Default::default() // This would be replaced with actual preservation
                });
            }
        }
        
        // Remove any blockers controlled by the eliminated player
        let blockers_to_remove: Vec<Entity> = combat_system.blockers
            .iter()
            .filter_map(|(blocker, _)| {
                if get_controller(*blocker) == Some(eliminated_player) {
                    Some(*blocker)
                } else {
                    None
                }
            })
            .collect();
        
        for blocker in blockers_to_remove {
            combat_system.blockers.remove(&blocker);
            
            // Update creature component to no longer be blocking
            if let Some(mut creature) = commands.get_entity(blocker) {
                creature.insert(Creature {
                    blocking: Vec::new(),
                    // Other fields preserved...
                    ..Default::default() // This would be replaced with actual preservation
                });
            }
        }
    }
}
}

Redirect Attack Effects

Some cards can redirect attacks to different players:

#![allow(unused)]
fn main() {
pub fn handle_attack_redirection(
    mut combat_system: ResMut<CombatSystem>,
    redirection_effects: Query<(Entity, &AttackRedirection)>,
) {
    // Process any attack redirection effects
    let redirections: Vec<(Entity, Entity)> = combat_system.attackers
        .iter()
        .filter_map(|(attacker, attack_data)| {
            for (_, redirection) in redirection_effects.iter() {
                if redirection.original_defender == attack_data.defender 
                   && redirection.applies_to(*attacker) {
                    return Some((*attacker, redirection.new_defender));
                }
            }
            None
        })
        .collect();
    
    // Apply redirections
    for (attacker, new_defender) in redirections {
        if let Some(attack_data) = combat_system.attackers.get_mut(&attacker) {
            attack_data.defender = new_defender;
        }
    }
}

#[derive(Component)]
pub struct AttackRedirection {
    pub original_defender: Entity,
    pub new_defender: Entity,
    pub condition: RedirectionCondition,
}

impl AttackRedirection {
    pub fn applies_to(&self, attacker: Entity) -> bool {
        match &self.condition {
            RedirectionCondition::AllAttackers => true,
            RedirectionCondition::AttackerWithPower { operator, value } => {
                // Implementation details omitted
                true
            },
            // Other conditions...
            _ => false,
        }
    }
}
}

Testing Strategy

Multiplayer Combat Unit Tests

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_multiple_attack_targets() {
        let mut app = App::new();
        app.add_systems(Update, validate_multiplayer_attacks);
        app.add_event::<GameEvent>();
        
        // Set up test environment
        let active_player = app.world.spawn(Player::default()).id();
        let opponent1 = app.world.spawn(Player::default()).id();
        let opponent2 = app.world.spawn(Player::default()).id();
        
        let attacker1 = app.world.spawn(Creature::default()).id();
        let attacker2 = app.world.spawn(Creature::default()).id();
        
        // Create turn manager
        let mut turn_manager = TurnManager::default();
        turn_manager.active_player_index = 0;
        turn_manager.player_order = vec![active_player, opponent1, opponent2];
        app.insert_resource(turn_manager);
        
        // Create combat system with attacks against multiple players
        let mut combat_system = CombatSystem::default();
        combat_system.attackers.insert(attacker1, AttackData {
            attacker: attacker1,
            defender: opponent1,
            is_commander: false,
            requirements: Vec::new(),
            restrictions: Vec::new(),
        });
        combat_system.attackers.insert(attacker2, AttackData {
            attacker: attacker2,
            defender: opponent2,
            is_commander: false,
            requirements: Vec::new(),
            restrictions: Vec::new(),
        });
        app.insert_resource(combat_system);
        
        // Run the system
        app.update();
        
        // Check for multiplay attack event
        let mut event_reader = app.world.resource_mut::<Events<GameEvent>>();
        let mut found_event = false;
        
        for event in event_reader.iter() {
            if let GameEvent::MultiplayerAttacksDeclared { .. } = event {
                found_event = true;
                break;
            }
        }
        
        assert!(found_event, "Multiplayer attack event not emitted");
    }
    
    #[test]
    fn test_goad_mechanic() {
        let mut app = App::new();
        app.add_systems(Update, apply_goad_requirements);
        
        // Set up test environment
        let active_player = app.world.spawn(Player::default()).id();
        let opponent1 = app.world.spawn(Player::default()).id();
        let opponent2 = app.world.spawn(Player::default()).id();
        
        // Create goaded creature
        let goaded_creature = app.world.spawn((
            Creature::default(),
            Controllable { controller: active_player },
            Goaded { source: opponent1, until_end_of_turn: true },
        )).id();
        
        // Create turn manager
        let mut turn_manager = TurnManager::default();
        turn_manager.active_player_index = 0;
        turn_manager.player_order = vec![active_player, opponent1, opponent2];
        app.insert_resource(turn_manager);
        
        // Create combat system
        let combat_system = CombatSystem::default();
        app.insert_resource(combat_system);
        
        // Run the system
        app.update();
        
        // Verify goad requirements were applied
        let combat_system = app.world.resource::<CombatSystem>();
        
        // Check that creature must attack
        let has_must_attack = combat_system.attack_requirements.get(&goaded_creature)
            .map_or(false, |reqs| reqs.iter().any(|req| matches!(req, AttackRequirement::MustAttack)));
        assert!(has_must_attack, "Goaded creature should have MustAttack requirement");
        
        // Check that creature can't attack goad source
        let has_cant_attack_source = combat_system.attack_restrictions.get(&goaded_creature)
            .map_or(false, |reqs| reqs.iter().any(|req| matches!(req, AttackRestriction::CantAttackPlayer(p) if *p == opponent1)));
        assert!(has_cant_attack_source, "Goaded creature should not be able to attack goad source");
    }
    
    #[test]
    fn test_monarch_mechanic() {
        let mut app = App::new();
        app.add_systems(Update, monarch_attack_trigger);
        app.add_event::<GameEvent>();
        
        // Set up test environment
        let player1 = app.world.spawn(Player::default()).id();
        let player2 = app.world.spawn(Player::default()).id();
        
        let attacker = app.world.spawn((
            Creature::default(),
            Controllable { controller: player2 },
        )).id();
        
        // Create turn manager with combat phase
        let mut turn_manager = TurnManager::default();
        turn_manager.current_phase = Phase::Combat(CombatStep::CombatDamage);
        app.insert_resource(turn_manager);
        
        // Set player1 as monarch
        app.insert_resource(Monarch(Some(player1)));
        
        // Create combat system with attack history
        let mut combat_system = CombatSystem::default();
        combat_system.attackers.insert(attacker, AttackData {
            attacker,
            defender: player1,
            is_commander: false,
            requirements: Vec::new(),
            restrictions: Vec::new(),
        });
        combat_system.combat_history.push_back(CombatEvent::DamageDealt {
            source: attacker,
            target: player1,
            amount: 3,
            is_commander_damage: false,
        });
        app.insert_resource(combat_system);
        
        // Run the system
        app.update();
        
        // Verify monarch changed
        let monarch = app.world.resource::<Monarch>();
        assert_eq!(monarch.0, Some(player2), "Monarch should have changed to player2");
    }
    
    // Additional tests...
}
}

Multiplayer Combat Integration Tests

#![allow(unused)]
fn main() {
#[cfg(test)]
mod integration_tests {
    use super::*;
    
    #[test]
    fn test_multiplayer_combat_sequence() {
        let mut builder = CombatScenarioBuilder::new();
        
        // Add multiple opponents
        let opponent1 = builder.add_player();
        let opponent2 = builder.add_player();
        
        // Add attackers for active player
        let attacker1 = builder.add_attacker(3, 3, builder.active_player, false);
        let attacker2 = builder.add_attacker(2, 2, builder.active_player, true); // Commander
        
        // Add blocker for first opponent
        let blocker = builder.add_blocker(2, 2, opponent1);
        
        // Declare attacks against multiple opponents
        builder.declare_attacks(vec![
            (attacker1, opponent1),
            (attacker2, opponent2),
        ]);
        
        // Declare blocks
        builder.declare_blocks(vec![
            (blocker, vec![attacker1]),
        ]);
        
        // Execute combat
        let result = builder.execute();
        
        // Verify results
        
        // Opponent1 should have lost no life (blocked) but blocker should be dead
        assert_eq!(result.player_life[&opponent1], 40);
        let blocker_status = result.creature_status.get(&blocker).unwrap();
        assert!(blocker_status.destroyed);
        
        // Opponent2 should have taken commander damage
        assert_eq!(result.player_life[&opponent2], 40 - 2);
        assert_eq!(result.commander_damage[&opponent2][&attacker2], 2);
    }
    
    #[test]
    fn test_player_elimination_during_combat() {
        let mut app = App::new();
        
        // Setup full game environment with multiple players
        // Implementation details omitted for brevity
        
        // Simulate combat damage that eliminates a player
        // Implementation details omitted for brevity
        
        // Verify that all attacks targeting the eliminated player are removed
        // Implementation details omitted for brevity
    }
    
    // Additional integration tests...
}
}

Multiplayer Combat System Tests

#![allow(unused)]
fn main() {
#[cfg(test)]
mod system_tests {
    use super::*;
    
    #[test]
    fn test_full_multiplayer_game() {
        let mut app = App::new();
        
        // Setup a 4-player Commander game
        let players = setup_four_player_game(&mut app);
        
        // Play through several turns with complex political interactions
        for _ in 0..10 {
            app.update();
            
            // Add various political actions between updates
            // (goad effects, attack redirection, monarch changes, etc.)
            // Implementation details omitted for brevity
        }
        
        // Verify multiplayer combat interactions worked as expected
        // Implementation details omitted for brevity
    }
    
    // Helper functions for system tests
    fn setup_four_player_game(app: &mut App) -> Vec<Entity> {
        // Implementation details omitted for brevity
        Vec::new()
    }
    
    // Additional system tests...
}
}

Performance Considerations

Multiplayer combat introduces additional computational complexity:

#![allow(unused)]
fn main() {
// Optimize attack target lookup
pub fn optimize_multiplayer_combat(
    mut combat_system: ResMut<CombatSystem>,
) {
    // Build attack target lookup table for faster validation
    let mut attack_target_map: HashMap<Entity, HashSet<Entity>> = HashMap::new();
    
    for (attacker, attack_data) in &combat_system.attackers {
        attack_target_map.entry(attack_data.defender)
            .or_insert_with(HashSet::new)
            .insert(*attacker);
    }
    
    combat_system.attack_target_map = attack_target_map;
}
}

UI Considerations

Multiplayer combat requires special attention to the user interface:

#![allow(unused)]
fn main() {
pub fn update_multiplayer_combat_ui(
    combat_system: Res<CombatSystem>,
    player_query: Query<(Entity, &Player)>,
    mut ui_state: ResMut<UiState>,
) {
    // Group attacks by defender for UI display
    let mut attacks_by_defender: HashMap<Entity, Vec<Entity>> = HashMap::new();
    
    for (attacker, attack_data) in &combat_system.attackers {
        attacks_by_defender.entry(attack_data.defender)
            .or_insert_with(Vec::new)
            .push(*attacker);
    }
    
    // Update UI state for each player
    for (player_entity, _) in player_query.iter() {
        // Display incoming attacks for this player
        if let Some(attackers) = attacks_by_defender.get(&player_entity) {
            ui_state.player_incoming_attacks.insert(player_entity, attackers.clone());
        } else {
            ui_state.player_incoming_attacks.insert(player_entity, Vec::new());
        }
    }
}
}

Networking Considerations

In a networked multiplayer game, commander-specific combat events need special handling:

#![allow(unused)]
fn main() {
pub fn replicate_multiplayer_combat_state(
    combat_system: Res<CombatSystem>,
    monarch: Res<Monarch>,
    mut replication: ResMut<Replication>,
) {
    // Replicate critical combat state
    replication.replicate_resource::<CombatSystem>();
    replication.replicate_resource::<Monarch>();
    
    // Replicate all combat-relevant components
    for (entity, _) in combat_system.attackers.iter() {
        replication.replicate_entity(*entity);
    }
    
    for (entity, _) in combat_system.blockers.iter() {
        replication.replicate_entity(*entity);
    }
}
}

Conclusion

Multiplayer combat in Commander adds significant complexity but also creates rich strategic gameplay. By properly implementing the systems described in this document, we ensure that players can fully experience the political dynamics and multiplayer interactions that make Commander such a beloved format. The implementation handles all the edge cases and unique mechanics while maintaining good performance even with four or more players.

Combat System

Overview

The Combat System is a critical component of the Commander game engine, handling all aspects of creature combat including attacks, blocks, damage assignment, and combat-specific abilities. This system is especially complex in Commander due to the multiplayer nature of the format and the special rules regarding commander damage.

Core Components

The combat system consists of several interconnected components:

1. Combat Phase Management - Handling the flow through combat steps
2. Attack Declaration System - Managing which creatures attack and who they attack
3. Block Declaration System - Managing how defending players assign blockers
4. Damage Assignment System - Calculating and applying combat damage
5. Commander Damage Tracking - Monitoring and accumulating commander damage
6. Combat Triggers - Handling abilities that trigger during combat

System Architecture

The combat system uses a modular design pattern to separate concerns:

#![allow(unused)]
fn main() {
// Core combat system resource
#[derive(Resource)]
pub struct CombatSystem {
    pub active_combat_step: Option<CombatStep>,
    pub attackers: HashMap<Entity, AttackData>,
    pub blockers: HashMap<Entity, BlockData>,
    pub combat_triggers: Vec<CombatTrigger>,
    pub damage_assignment_order: Vec<Entity>,
    pub combat_history: VecDeque<CombatEvent>,
}

// Data for an attacking creature
#[derive(Debug, Clone)]
pub struct AttackData {
    pub attacker: Entity,
    pub defender: Entity, // Can be a player or planeswalker
    pub is_commander: bool,
    pub requirements: Vec<AttackRequirement>,
    pub restrictions: Vec<AttackRestriction>,
}

// Data for a blocking creature
#[derive(Debug, Clone)]
pub struct BlockData {
    pub blocker: Entity,
    pub blocked_attackers: Vec<Entity>,
    pub requirements: Vec<BlockRequirement>,
    pub restrictions: Vec<BlockRestriction>,
}

// Combat event for history tracking
#[derive(Debug, Clone)]
pub enum CombatEvent {
    BeginCombat { turn: u32, active_player: Entity },
    AttackDeclared { attacker: Entity, defender: Entity },
    BlockDeclared { blocker: Entity, attacker: Entity },
    DamageDealt { source: Entity, target: Entity, amount: u32, is_commander_damage: bool },
    CombatEnded { turn: u32 },
}
}

Integration with Other Systems

The combat system interfaces with several other game systems:

• Turn Manager - For phase control and player ordering
• Stack System - For handling combat-triggered abilities
• Damage System - For applying damage and handling prevention/redirection effects
• Game State System - For tracking changes to the game state during combat
• Player System - For player state changes (life totals, commander damage)

Documentation Structure

This documentation is organized into several parts:

• Combat Phases - Detailed implementation of each combat step
• Commander Damage - Special handling of commander damage
• Multiplayer Combat - Combat in a multiplayer environment
• Combat Abilities - Implementation of combat-specific abilities
• Combat Verification - Testing and verification approach

Each section contains detailed information about implementation, edge cases, and testing strategies for that aspect of the combat system.

Combat Verification

Overview

A robust verification framework is critical for ensuring that the Combat System correctly implements the complex rules of Magic: The Gathering's Commander format. This document outlines our comprehensive testing approach, which covers unit testing, integration testing, system testing, and end-to-end testing strategies to verify both basic functionality and edge cases.

Testing Framework Architecture

#![allow(unused)]
fn main() {
// Test utility for setting up combat scenarios
pub struct CombatScenarioBuilder {
    pub app: App,
    pub active_player: Entity,
    pub players: Vec<Entity>,
    pub attackers: Vec<Entity>,
    pub blockers: Vec<Entity>,
    pub effects: Vec<(Entity, Effect)>,
}

impl CombatScenarioBuilder {
    pub fn new() -> Self {
        let mut app = App::new();
        
        // Add essential plugins and systems
        app.add_plugins(MinimalPlugins)
           .add_plugins(TestTurnSystemPlugin)
           .add_plugins(TestCombatSystemPlugin);
        
        // Initialize resources
        app.insert_resource(CombatSystem::default());
        app.insert_resource(TurnManager::default());
        
        // Create default active player
        let active_player = app.world.spawn(Player {
            life_total: 40,
            commander_damage: HashMap::new(),
            ..Default::default()
        }).id();
        
        Self {
            app,
            active_player,
            players: vec![active_player],
            attackers: Vec::new(),
            blockers: Vec::new(),
            effects: Vec::new(),
        }
    }
    
    // Add a player to the scenario
    pub fn add_player(&mut self) -> Entity {
        let player = self.app.world.spawn(Player {
            life_total: 40,
            commander_damage: HashMap::new(),
            ..Default::default()
        }).id();
        
        self.players.push(player);
        player
    }
    
    // Add an attacking creature
    pub fn add_attacker(&mut self, 
                        power: u32, 
                        toughness: u32, 
                        controller: Entity, 
                        is_commander: bool) -> Entity {
        let mut components = (
            Card::default(),
            Creature {
                power,
                toughness,
                attacking: None,
                blocking: Vec::new(),
                ..Default::default()
            },
            Controllable { controller },
        );
        
        let entity = if is_commander {
            self.app.world.spawn((components, Commander)).id()
        } else {
            self.app.world.spawn(components).id()
        };
        
        self.attackers.push(entity);
        entity
    }
    
    // Add a blocking creature
    pub fn add_blocker(&mut self, 
                      power: u32, 
                      toughness: u32, 
                      controller: Entity) -> Entity {
        let entity = self.app.world.spawn((
            Card::default(),
            Creature {
                power,
                toughness,
                attacking: None,
                blocking: Vec::new(),
                ..Default::default()
            },
            Controllable { controller },
        )).id();
        
        self.blockers.push(entity);
        entity
    }
    
    // Add an effect to an entity
    pub fn add_effect(&mut self, entity: Entity, effect: Effect) {
        self.effects.push((entity, effect));
        
        // Apply the effect to the entity
        let mut effects = self.app.world.entity_mut(entity)
            .get_mut::<ActiveEffects>()
            .unwrap_or_else(|| {
                self.app.world.entity_mut(entity).insert(ActiveEffects(Vec::new()));
                self.app.world.entity_mut(entity).get_mut::<ActiveEffects>().unwrap()
            });
        
        effects.0.push(effect);
    }
    
    // Set up attacks
    pub fn declare_attacks(&mut self, attacks: Vec<(Entity, Entity)>) {
        let mut combat_system = self.app.world.resource_mut::<CombatSystem>();
        
        for (attacker, defender) in attacks {
            // Update creature component
            let mut attacker_entity = self.app.world.entity_mut(attacker);
            let mut creature = attacker_entity.get_mut::<Creature>().unwrap();
            creature.attacking = Some(defender);
            
            // Check if attacker is a commander
            let is_commander = attacker_entity.contains::<Commander>();
            
            // Add to combat system
            combat_system.attackers.insert(attacker, AttackData {
                attacker,
                defender,
                is_commander,
                requirements: Vec::new(),
                restrictions: Vec::new(),
            });
        }
    }
    
    // Set up blocks
    pub fn declare_blocks(&mut self, blocks: Vec<(Entity, Vec<Entity>)>) {
        let mut combat_system = self.app.world.resource_mut::<CombatSystem>();
        
        for (blocker, blocked_attackers) in blocks {
            // Update creature component
            let mut blocker_entity = self.app.world.entity_mut(blocker);
            let mut creature = blocker_entity.get_mut::<Creature>().unwrap();
            creature.blocking = blocked_attackers.clone();
            
            // Add to combat system
            combat_system.blockers.insert(blocker, BlockData {
                blocker,
                blocked_attackers,
                requirements: Vec::new(),
                restrictions: Vec::new(),
            });
        }
    }
    
    // Advance to a specific combat step
    pub fn advance_to(&mut self, step: CombatStep) {
        let mut turn_manager = self.app.world.resource_mut::<TurnManager>();
        turn_manager.current_phase = Phase::Combat(step);
        
        let mut combat_system = self.app.world.resource_mut::<CombatSystem>();
        combat_system.active_combat_step = Some(step);
    }
    
    // Execute combat and return results
    pub fn execute(&mut self) -> CombatResult {
        // Run the relevant systems based on the current step
        match self.app.world.resource::<CombatSystem>().active_combat_step {
            Some(CombatStep::Beginning) => {
                self.app.update_with_system(beginning_of_combat_system);
            }
            Some(CombatStep::DeclareAttackers) => {
                self.app.update_with_system(declare_attackers_system);
            }
            Some(CombatStep::DeclareBlockers) => {
                self.app.update_with_system(declare_blockers_system);
            }
            Some(CombatStep::FirstStrike) => {
                self.app.update_with_system(first_strike_damage_system);
            }
            Some(CombatStep::CombatDamage) => {
                self.app.update_with_system(apply_combat_damage_system);
            }
            Some(CombatStep::End) => {
                self.app.update_with_system(end_of_combat_system);
            }
            None => {
                // Run all systems in sequence
                self.advance_to(CombatStep::Beginning);
                self.app.update_with_system(beginning_of_combat_system);
                
                self.advance_to(CombatStep::DeclareAttackers);
                self.app.update_with_system(declare_attackers_system);
                
                self.advance_to(CombatStep::DeclareBlockers);
                self.app.update_with_system(declare_blockers_system);
                
                // Check if first strike is needed
                if self.has_first_strike_creatures() {
                    self.advance_to(CombatStep::FirstStrike);
                    self.app.update_with_system(first_strike_damage_system);
                }
                
                self.advance_to(CombatStep::CombatDamage);
                self.app.update_with_system(apply_combat_damage_system);
                
                self.advance_to(CombatStep::End);
                self.app.update_with_system(end_of_combat_system);
            }
        }
        
        // Collect and return results
        self.collect_combat_results()
    }
    
    // Helper to check if any creatures have first strike
    fn has_first_strike_creatures(&self) -> bool {
        for attacker in &self.attackers {
            if let Ok(creature) = self.app.world.entity(*attacker).get::<Creature>() {
                if creature.has_ability(Ability::Keyword(Keyword::FirstStrike)) || 
                   creature.has_ability(Ability::Keyword(Keyword::DoubleStrike)) {
                    return true;
                }
            }
        }
        
        for blocker in &self.blockers {
            if let Ok(creature) = self.app.world.entity(*blocker).get::<Creature>() {
                if creature.has_ability(Ability::Keyword(Keyword::FirstStrike)) || 
                   creature.has_ability(Ability::Keyword(Keyword::DoubleStrike)) {
                    return true;
                }
            }
        }
        
        false
    }
    
    // Collect results of combat
    fn collect_combat_results(&self) -> CombatResult {
        let mut result = CombatResult::default();
        
        // Collect player life totals and commander damage
        for player in &self.players {
            if let Ok(player_component) = self.app.world.entity(*player).get::<Player>() {
                result.player_life.insert(*player, player_component.life_total);
                result.commander_damage.insert(*player, player_component.commander_damage.clone());
            }
        }
        
        // Collect creature status
        for creature in self.attackers.iter().chain(self.blockers.iter()) {
            if let Ok(creature_component) = self.app.world.entity(*creature).get::<Creature>() {
                result.creature_status.insert(*creature, CreatureStatus {
                    power: creature_component.power,
                    toughness: creature_component.toughness,
                    damage: creature_component.damage,
                    destroyed: self.app.world.entity(*creature).contains::<Destroyed>(),
                    tapped: self.app.world.entity(*creature).contains::<Tapped>(),
                });
            }
        }
        
        // Collect combat events
        let combat_system = self.app.world.resource::<CombatSystem>();
        result.combat_events = combat_system.combat_history.clone();
        
        result
    }
}

// Structure to hold combat test results
#[derive(Default)]
pub struct CombatResult {
    pub player_life: HashMap<Entity, i32>,
    pub commander_damage: HashMap<Entity, HashMap<Entity, u32>>,
    pub creature_status: HashMap<Entity, CreatureStatus>,
    pub combat_events: VecDeque<CombatEvent>,
}

#[derive(Default)]
pub struct CreatureStatus {
    pub power: u32,
    pub toughness: u32,
    pub damage: u32,
    pub destroyed: bool,
    pub tapped: bool,
}
}

Unit Testing

Combat Steps Tests

Each combat step has dedicated unit tests to verify its functionality in isolation:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod beginning_of_combat_tests {
    use super::*;
    
    #[test]
    fn test_beginning_of_combat_initialization() {
        let mut builder = CombatScenarioBuilder::new();
        
        // Add some creatures
        let opponent = builder.add_player();
        builder.add_attacker(2, 2, builder.active_player, false);
        builder.add_attacker(3, 3, builder.active_player, true); // Commander
        
        // Set up the beginning of combat step
        builder.advance_to(CombatStep::Beginning);
        
        // Execute and get results
        let result = builder.execute();
        
        // Verify combat system is properly initialized
        let combat_system = builder.app.world.resource::<CombatSystem>();
        assert_eq!(combat_system.active_combat_step, Some(CombatStep::Beginning));
        
        // Verify begin combat event was recorded
        assert!(result.combat_events.iter().any(|event| 
            matches!(event, CombatEvent::BeginCombat { .. })));
    }
    
    // Additional tests...
}

#[cfg(test)]
mod declare_attackers_tests {
    use super::*;
    
    #[test]
    fn test_declare_attackers_basic() {
        let mut builder = CombatScenarioBuilder::new();
        
        // Add some creatures and a player to attack
        let opponent = builder.add_player();
        let attacker1 = builder.add_attacker(2, 2, builder.active_player, false);
        let attacker2 = builder.add_attacker(3, 3, builder.active_player, true); // Commander
        
        // Set up attacks
        builder.advance_to(CombatStep::DeclareAttackers);
        builder.declare_attacks(vec![
            (attacker1, opponent),
            (attacker2, opponent),
        ]);
        
        // Execute and get results
        let result = builder.execute();
        
        // Verify creatures are marked as attacking
        let combat_system = builder.app.world.resource::<CombatSystem>();
        assert_eq!(combat_system.attackers.len(), 2);
        
        // Verify attack events were recorded
        assert_eq!(
            result.combat_events.iter()
                .filter(|event| matches!(event, CombatEvent::AttackDeclared { .. }))
                .count(),
            2
        );
        
        // Verify creatures are tapped
        for (entity, status) in &result.creature_status {
            assert!(status.tapped);
        }
    }
    
    // Additional tests...
}

// Similar unit tests for other combat steps...
}

Edge Case Tests

Dedicated tests for all identified edge cases:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod edge_case_tests {
    use super::*;
    
    #[test]
    fn test_indestructible_creatures() {
        let mut builder = CombatScenarioBuilder::new();
        
        // Setup creatures
        let opponent = builder.add_player();
        let attacker = builder.add_attacker(2, 2, builder.active_player, false);
        let blocker = builder.add_blocker(4, 4, opponent);
        
        // Make attacker indestructible
        builder.add_effect(attacker, Effect::Indestructible);
        
        // Set up combat
        builder.advance_to(CombatStep::DeclareAttackers);
        builder.declare_attacks(vec![(attacker, opponent)]);
        
        builder.advance_to(CombatStep::DeclareBlockers);
        builder.declare_blocks(vec![(blocker, vec![attacker])]);
        
        // Execute full combat
        builder.advance_to(CombatStep::CombatDamage);
        let result = builder.execute();
        
        // Verify attacker received lethal damage but wasn't destroyed
        let attacker_status = result.creature_status.get(&attacker).unwrap();
        assert_eq!(attacker_status.damage, 4); // Received damage
        assert!(!attacker_status.destroyed); // But not destroyed
        
        // Verify blocker took damage
        let blocker_status = result.creature_status.get(&blocker).unwrap();
        assert_eq!(blocker_status.damage, 2);
        assert!(!blocker_status.destroyed);
    }
    
    #[test]
    fn test_deathtouch() {
        let mut builder = CombatScenarioBuilder::new();
        
        // Setup creatures
        let opponent = builder.add_player();
        let attacker = builder.add_attacker(1, 1, builder.active_player, false);
        let blocker = builder.add_blocker(10, 10, opponent);
        
        // Add deathtouch to attacker
        builder.add_effect(attacker, Effect::Keyword(Keyword::Deathtouch));
        
        // Set up combat
        builder.advance_to(CombatStep::DeclareAttackers);
        builder.declare_attacks(vec![(attacker, opponent)]);
        
        builder.advance_to(CombatStep::DeclareBlockers);
        builder.declare_blocks(vec![(blocker, vec![attacker])]);
        
        // Execute full combat
        builder.advance_to(CombatStep::CombatDamage);
        let result = builder.execute();
        
        // Verify blocker was destroyed by deathtouch
        let blocker_status = result.creature_status.get(&blocker).unwrap();
        assert!(blocker_status.destroyed);
        
        // Verify attacker was also destroyed 
        let attacker_status = result.creature_status.get(&attacker).unwrap();
        assert!(attacker_status.destroyed);
    }
    
    #[test]
    fn test_trample() {
        let mut builder = CombatScenarioBuilder::new();
        
        // Setup creatures
        let opponent = builder.add_player();
        let attacker = builder.add_attacker(6, 6, builder.active_player, false);
        let blocker = builder.add_blocker(2, 2, opponent);
        
        // Add trample to attacker
        builder.add_effect(attacker, Effect::Keyword(Keyword::Trample));
        
        // Set up combat
        builder.advance_to(CombatStep::DeclareAttackers);
        builder.declare_attacks(vec![(attacker, opponent)]);
        
        builder.advance_to(CombatStep::DeclareBlockers);
        builder.declare_blocks(vec![(blocker, vec![attacker])]);
        
        // Execute full combat
        builder.advance_to(CombatStep::CombatDamage);
        let result = builder.execute();
        
        // Verify opponent took trample damage
        assert_eq!(result.player_life[&opponent], 40 - 4); // 6 power - 2 toughness = 4 damage
        
        // Verify blocker was destroyed
        let blocker_status = result.creature_status.get(&blocker).unwrap();
        assert!(blocker_status.destroyed);
    }
    
    #[test]
    fn test_multiple_blockers() {
        let mut builder = CombatScenarioBuilder::new();
        
        // Setup creatures
        let opponent = builder.add_player();
        let attacker = builder.add_attacker(5, 5, builder.active_player, false);
        let blocker1 = builder.add_blocker(2, 2, opponent);
        let blocker2 = builder.add_blocker(2, 2, opponent);
        
        // Set up combat
        builder.advance_to(CombatStep::DeclareAttackers);
        builder.declare_attacks(vec![(attacker, opponent)]);
        
        builder.advance_to(CombatStep::DeclareBlockers);
        builder.declare_blocks(vec![
            (blocker1, vec![attacker]),
            (blocker2, vec![attacker]),
        ]);
        
        // Add damage assignment order
        let mut combat_system = builder.app.world.resource_mut::<CombatSystem>();
        combat_system.damage_assignment_order = vec![blocker1, blocker2];
        
        // Execute full combat
        builder.advance_to(CombatStep::CombatDamage);
        let result = builder.execute();
        
        // Verify both blockers were destroyed
        let blocker1_status = result.creature_status.get(&blocker1).unwrap();
        assert!(blocker1_status.destroyed);
        
        let blocker2_status = result.creature_status.get(&blocker2).unwrap();
        assert!(blocker2_status.destroyed);
        
        // Verify attacker took damage from both blockers
        let attacker_status = result.creature_status.get(&attacker).unwrap();
        assert_eq!(attacker_status.damage, 4);
        assert!(!attacker_status.destroyed);
        
        // Verify player took no damage
        assert_eq!(result.player_life[&opponent], 40);
    }
    
    // Many more edge case tests...
}
}

Integration Tests

Integration tests verify that different parts of the combat system work together correctly:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod integration_tests {
    use super::*;
    
    #[test]
    fn test_full_combat_sequence() {
        let mut builder = CombatScenarioBuilder::new();
        
        // Setup a complex combat scenario
        let opponent = builder.add_player();
        let attacker1 = builder.add_attacker(3, 3, builder.active_player, false);
        let attacker2 = builder.add_attacker(4, 4, builder.active_player, true); // Commander
        let blocker1 = builder.add_blocker(2, 2, opponent);
        let blocker2 = builder.add_blocker(5, 5, opponent);
        
        // Add some abilities
        builder.add_effect(attacker1, Effect::Keyword(Keyword::Trample));
        builder.add_effect(blocker2, Effect::Keyword(Keyword::Deathtouch));
        
        // Run through the entire combat sequence
        builder.declare_attacks(vec![
            (attacker1, opponent),
            (attacker2, opponent),
        ]);
        
        builder.declare_blocks(vec![
            (blocker1, vec![attacker1]),
            (blocker2, vec![attacker2]),
        ]);
        
        // Execute and get results
        let result = builder.execute();
        
        // Verify final state
        
        // Attacker1 should have dealt trample damage
        assert_eq!(result.player_life[&opponent], 40 - 1); // 3 power - 2 toughness = 1 damage
        
        // Attacker2 (commander) should be destroyed by deathtouch
        let attacker2_status = result.creature_status.get(&attacker2).unwrap();
        assert!(attacker2_status.destroyed);
        
        // Blocker1 should be destroyed
        let blocker1_status = result.creature_status.get(&blocker1).unwrap();
        assert!(blocker1_status.destroyed);
        
        // Blocker2 should take damage but survive
        let blocker2_status = result.creature_status.get(&blocker2).unwrap();
        assert_eq!(blocker2_status.damage, 4);
        assert!(!blocker2_status.destroyed);
        
        // Commander damage should be tracked
        assert_eq!(result.commander_damage[&opponent][&attacker2], 4);
    }
    
    #[test]
    fn test_complex_combat_with_triggers() {
        // Test implementation omitted for brevity
        // This would test combat with abilities that trigger on attack, block, or damage
    }
    
    #[test]
    fn test_multiple_turns_commander_damage() {
        // Test that tracks commander damage across multiple turns
        // Implementation omitted for brevity
    }
    
    // Additional integration tests...
}
}

System Tests

System tests verify the combat system's interaction with other systems:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod system_tests {
    use super::*;
    
    #[test]
    fn test_combat_with_stack_interaction() {
        let mut app = App::new();
        
        // Add complete game systems
        app.add_plugins(MinimalPlugins)
           .add_plugins(GameLogicPlugins);
        
        // Set up test entities and start a game
        // Implementation omitted for brevity
        
        // Create a combat scenario with abilities that go on the stack
        // Implementation omitted for brevity
        
        // Run the game until combat is complete
        for _ in 0..20 { // Limit iterations to prevent infinite loops
            app.update();
            
            // Check if combat is complete
            let combat_system = app.world.resource::<CombatSystem>();
            if combat_system.active_combat_step == Some(CombatStep::End) {
                break;
            }
        }
        
        // Verify stack interactions worked correctly
        // Implementation omitted for brevity
    }
    
    #[test]
    fn test_combat_with_state_changes() {
        // Test that combat properly interacts with game state changes
        // Implementation omitted for brevity
    }
    
    // Additional system tests...
}
}

End-to-End Tests

End-to-end tests verify the combat system in the context of a complete game:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod e2e_tests {
    use super::*;
    
    #[test]
    fn test_complete_game_with_combat() {
        let mut app = App::new();
        
        // Add complete game plugins
        app.add_plugins(DefaultPlugins)
           .add_plugins(GamePlugins);
        
        // Set up a complete game with multiple players
        setup_complete_game(&mut app, 4); // 4 players
        
        // Play through several turns
        for _ in 0..10 { // 10 turns
            play_turn(&mut app);
        }
        
        // Verify game state
        let game_state = app.world.resource::<GameState>();
        
        // Check remaining players
        let player_query = app.world.query_filtered::<Entity, With<Player>>();
        let remaining_players = player_query.iter(&app.world).count();
        
        // In most cases, we should still have multiple players
        assert!(remaining_players > 1, "Game ended too quickly");
        
        // Verify commander damage has been dealt
        let player_query = app.world.query::<&Player>();
        let has_commander_damage = player_query
            .iter(&app.world)
            .any(|player| !player.commander_damage.is_empty());
        
        assert!(has_commander_damage, "No commander damage was dealt in the game");
    }
    
    #[test]
    fn test_commander_damage_victory() {
        // Test a game where a player wins via commander damage
        // Implementation omitted for brevity
    }
    
    // Helper function to play a single turn
    fn play_turn(app: &mut App) {
        // Get current phase
        let turn_manager = app.world.resource::<TurnManager>();
        let start_phase = turn_manager.current_phase;
        
        // Run updates until we complete a turn
        for _ in 0..100 { // Limit iterations to prevent infinite loops
            app.update();
            
            let turn_manager = app.world.resource::<TurnManager>();
            
            // If we've come back to the same phase, we've completed a turn
            if turn_manager.current_phase == start_phase 
               && turn_manager.active_player_index != turn_manager.active_player_index {
                break;
            }
        }
    }
    
    // Helper function to set up a complete game
    fn setup_complete_game(app: &mut App, num_players: usize) {
        // Implementation omitted for brevity
    }
    
    // Additional end-to-end tests...
}
}

Property-Based Testing

We also employ property-based testing to verify invariants across randomized scenarios:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod property_tests {
    use super::*;
    use proptest::prelude::*;
    
    proptest! {
        #[test]
        fn commander_damage_consistency(
            // Generate random commander power between 1 and 10
            commander_power in 1u32..10,
            // Generate random number of combat rounds between 1 and 5
            combat_rounds in 1usize..5
        ) {
            // Setup combat scenario with commander of specified power
            let mut builder = CombatScenarioBuilder::new();
            let opponent = builder.add_player();
            let commander = builder.add_attacker(commander_power, commander_power, builder.active_player, true);
            
            // Track expected damage
            let mut expected_damage = 0;
            
            // Simulate multiple rounds of combat
            for _ in 0..combat_rounds {
                builder.advance_to(CombatStep::DeclareAttackers);
                builder.declare_attacks(vec![(commander, opponent)]);
                
                // No blocks for simplicity
                builder.advance_to(CombatStep::DeclareBlockers);
                
                // Execute combat damage
                builder.advance_to(CombatStep::CombatDamage);
                builder.execute();
                
                // Update expected damage
                expected_damage += commander_power;
            }
            
            // Check final state
            let result = builder.collect_combat_results();
            
            // Verify commander damage matches expected total
            prop_assert_eq!(
                result.commander_damage[&opponent][&commander],
                expected_damage
            );
            
            // Verify life total reflects damage
            prop_assert_eq!(
                result.player_life[&opponent],
                40 - (expected_damage as i32)
            );
        }
        
        #[test]
        fn multiple_attackers_damage_distribution(
            // Generate 1-5 attackers with power 1-5 each
            attackers in prop::collection::vec((1u32..5, 1u32..5), 1..5)
        ) {
            let mut builder = CombatScenarioBuilder::new();
            let opponent = builder.add_player();
            
            // Create attackers and track total power
            let mut attacker_entities = Vec::new();
            let mut total_power = 0;
            
            for (power, toughness) in attackers {
                let attacker = builder.add_attacker(
                    power, toughness, builder.active_player, false);
                attacker_entities.push(attacker);
                total_power += power;
            }
            
            // Declare all attackers attacking opponent
            builder.advance_to(CombatStep::DeclareAttackers);
            builder.declare_attacks(
                attacker_entities.iter()
                    .map(|&a| (a, opponent))
                    .collect()
            );
            
            // No blocks
            builder.advance_to(CombatStep::DeclareBlockers);
            
            // Execute combat damage
            builder.advance_to(CombatStep::CombatDamage);
            let result = builder.execute();
            
            // Verify opponent's life total correctly reflects all damage
            prop_assert_eq!(
                result.player_life[&opponent],
                40 - (total_power as i32)
            );
        }
    }
}
}

Test Coverage Goals

Our testing strategy aims for the following coverage metrics:

1. Line Coverage: At least 90% of all combat-related code
2. Branch Coverage: At least 85% of all conditional branches
3. Path Coverage: At least 75% of all execution paths
4. Edge Case Coverage: 100% of identified edge cases have dedicated tests

Continuous Integration

All combat tests are integrated into the CI pipeline with the following workflow:

1. Unit tests run on every commit
2. Integration tests run on every PR
3. System and end-to-end tests run nightly
4. Coverage reports generated after each test run

Debugging Tools

To assist with debugging, we provide specialized tools:

#![allow(unused)]
fn main() {
/// Utility for debugging combat scenarios
pub fn debug_combat_state(combat_system: &CombatSystem, world: &World) {
    println!("=== COMBAT DEBUG STATE ===");
    
    // Print current combat step
    println!("Combat Step: {:?}", combat_system.active_combat_step);
    
    // Print attackers
    println!("\nAttackers:");
    for (entity, attack_data) in &combat_system.attackers {
        if let Ok((_, creature, _)) = world.query::<(Entity, &Creature, Option<&Commander>)>().get(world, *entity) {
            println!("  {:?} ({}:{}) attacking {:?}{}",
                entity,
                creature.power,
                creature.toughness,
                attack_data.defender,
                if attack_data.is_commander { " [COMMANDER]" } else { "" }
            );
        }
    }
    
    // Print blockers
    println!("\nBlockers:");
    for (entity, block_data) in &combat_system.blockers {
        if let Ok((_, creature)) = world.query::<(Entity, &Creature)>().get(world, *entity) {
            println!("  {:?} ({}:{}) blocking: {:?}",
                entity,
                creature.power,
                creature.toughness,
                block_data.blocked_attackers
            );
        }
    }
    
    // Print combat history
    println!("\nCombat History:");
    for (i, event) in combat_system.combat_history.iter().enumerate() {
        println!("  [{}] {:?}", i, event);
    }
    
    println!("=========================");
}
}

Verification Strategy Evolution

Our verification approach is not static; it evolves over time:

1. New edge cases identified during testing or gameplay are added to the test suite
2. Performance bottlenecks identified through testing are addressed
3. Test frameworks are updated as the combat system evolves
4. Regression tests are added for any bugs found in production

By following this comprehensive verification strategy, we ensure the Commander combat system correctly implements all rules, handles edge cases properly, and provides a robust foundation for the game engine.

Beginning of Combat Step

Overview

The Beginning of Combat step is the first step of the Combat Phase in Magic: The Gathering. This step serves as a transition between the pre-combat Main Phase and the declaration of attackers. It provides a crucial window for players to cast instants and activate abilities before attackers are declared. This document details the implementation of the Beginning of Combat step in our Commander game engine.

Core Implementation

Phase Structure

The Beginning of Combat step is implemented as part of the overall combat phase system:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CombatStep {
    BeginningOfCombat,
    DeclareAttackers,
    DeclareBlockers,
    CombatDamage,
    EndOfCombat,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Phase {
    // Other phases...
    Combat(CombatStep),
    // Other phases...
}
}

Beginning of Combat System

The core system that handles the Beginning of Combat step:

#![allow(unused)]
fn main() {
pub fn beginning_of_combat_system(
    mut commands: Commands,
    turn_manager: Res<TurnManager>,
    mut game_events: EventWriter<GameEvent>,
    active_player: Query<Entity, With<ActivePlayer>>,
    mut next_phase: ResMut<NextState<Phase>>,
    mut priority_system: ResMut<PrioritySystem>,
) {
    // Only run during Beginning of Combat
    if turn_manager.current_phase != Phase::Combat(CombatStep::BeginningOfCombat) {
        return;
    }

    // If this is the first time entering the step
    if !priority_system.priority_given {
        // Emit Beginning of Combat event
        let active_player_entity = active_player.single();
        game_events.send(GameEvent::BeginningOfCombat {
            player: active_player_entity,
        });
        
        // Clear any "until end of combat" effects from previous turns
        commands.run_system(clear_end_of_combat_effects);
        
        // Initialize any tracked combat data
        commands.insert_resource(CombatData::default());
        
        // Grant priority to active player
        priority_system.grant_initial_priority();
    }
    
    // If all players have passed priority without adding to the stack
    if priority_system.all_players_passed() && !priority_system.stack_changed {
        // Proceed to Declare Attackers step
        next_phase.set(Phase::Combat(CombatStep::DeclareAttackers));
        priority_system.priority_given = false;
    }
}
}

Event Triggers

The beginning of combat step triggers various abilities:

#![allow(unused)]
fn main() {
pub fn beginning_of_combat_triggers(
    turn_manager: Res<TurnManager>,
    mut ability_triggers: ResMut<AbilityTriggerQueue>,
    trigger_sources: Query<(Entity, &AbilityTrigger)>,
) {
    // Only run during Beginning of Combat
    if turn_manager.current_phase != Phase::Combat(CombatStep::BeginningOfCombat) {
        return;
    }
    
    // Process all "at beginning of combat" triggers
    for (entity, trigger) in trigger_sources.iter() {
        if let TriggerCondition::BeginningOfCombat { controller_only } = trigger.condition {
            let should_trigger = if controller_only {
                // Only trigger for the active player's permanents
                // Implementation details omitted
                true
            } else {
                // Trigger for all permanents with this trigger
                true
            };
            
            if should_trigger {
                ability_triggers.queue.push_back(AbilityTriggerEvent {
                    source: entity,
                    trigger: trigger.clone(),
                    targets: Vec::new(), // Will be filled later in target selection
                });
            }
        }
    }
}
}

Multiplayer Considerations

In Commander, the Beginning of Combat step needs to handle multiplayer-specific considerations:

#![allow(unused)]
fn main() {
pub fn multiplayer_beginning_of_combat(
    turn_manager: Res<TurnManager>,
    player_query: Query<(Entity, &Player)>,
    mut game_events: EventWriter<GameEvent>,
) {
    // Only run during Beginning of Combat
    if turn_manager.current_phase != Phase::Combat(CombatStep::BeginningOfCombat) {
        return;
    }
    
    // Notify all players about the beginning of combat
    let active_player = turn_manager.get_active_player();
    
    // Broadcast to all players
    for (player_entity, _) in player_query.iter() {
        game_events.send(GameEvent::PhaseChange {
            phase: Phase::Combat(CombatStep::BeginningOfCombat),
            player: active_player,
            notification_target: player_entity,
        });
    }
}
}

Ability Types in Beginning of Combat

Static Abilities

Static abilities that specifically affect combat are evaluated during this step:

#![allow(unused)]
fn main() {
pub fn evaluate_combat_static_abilities(
    mut commands: Commands,
    turn_manager: Res<TurnManager>,
    static_ability_query: Query<(Entity, &StaticAbility)>,
    creature_query: Query<(Entity, &Creature, &Controllable)>,
) {
    // Only run during Beginning of Combat
    if turn_manager.current_phase != Phase::Combat(CombatStep::BeginningOfCombat) {
        return;
    }
    
    // Apply "can't attack" effects
    for (entity, static_ability) in static_ability_query.iter() {
        match static_ability.effect {
            StaticEffect::CantAttack { target, condition } => {
                // Apply can't attack markers to appropriate creatures
                for (creature_entity, _, controllable) in creature_query.iter() {
                    if target.matches(creature_entity) && condition.is_met(creature_entity) {
                        commands.entity(creature_entity).insert(CantAttack {
                            source: entity,
                            duration: static_ability.duration,
                        });
                    }
                }
            },
            StaticEffect::CantBlock { target, condition } => {
                // Apply can't block markers to appropriate creatures
                for (creature_entity, _, controllable) in creature_query.iter() {
                    if target.matches(creature_entity) && condition.is_met(creature_entity) {
                        commands.entity(creature_entity).insert(CantBlock {
                            source: entity,
                            duration: static_ability.duration,
                        });
                    }
                }
            },
            // Other combat-relevant static effects...
            _ => {}
        }
    }
}
}

Triggered Abilities

Abilities that trigger at the beginning of combat:

#![allow(unused)]
fn main() {
#[derive(Component)]
pub struct AbilityTrigger {
    pub condition: TriggerCondition,
    pub effect: TriggeredEffect,
}

#[derive(Clone)]
pub enum TriggerCondition {
    BeginningOfCombat { controller_only: bool },
    // Other trigger conditions...
}

// Example of a "beginning of combat" triggered ability
pub fn assemble_megatron_trigger(
    turn_manager: Res<TurnManager>,
    megatron_query: Query<(Entity, &Controllable), With<Megatron>>,
    mut game_events: EventWriter<GameEvent>,
    mut ability_triggers: ResMut<AbilityTriggerQueue>,
) {
    // Only run during Beginning of Combat
    if turn_manager.current_phase != Phase::Combat(CombatStep::BeginningOfCombat) {
        return;
    }
    
    let active_player = turn_manager.get_active_player();
    
    for (entity, controllable) in megatron_query.iter() {
        // Only trigger for the active player's Megatron
        if controllable.controller == active_player {
            ability_triggers.queue.push_back(AbilityTriggerEvent {
                source: entity,
                trigger: AbilityTrigger {
                    condition: TriggerCondition::BeginningOfCombat { controller_only: true },
                    effect: TriggeredEffect::AssembleMegatron,
                },
                targets: Vec::new(),
            });
        }
    }
}
}

Edge Cases and Special Interactions

Cleanup Actions

Sometimes effects need to be cleaned up at the beginning of combat:

#![allow(unused)]
fn main() {
pub fn clear_end_of_combat_effects(
    mut commands: Commands,
    effect_query: Query<(Entity, &EndOfCombatEffect)>,
) {
    for (entity, effect) in effect_query.iter() {
        if effect.cleanup_at_next_beginning_of_combat {
            // Remove the effect component
            commands.entity(entity).remove::<EndOfCombatEffect>();
            
            // Apply any cleanup logic specific to this effect
            match effect.effect_type {
                EndOfCombatEffectType::TemporaryPowerBoost => {
                    commands.entity(entity).remove::<PowerToughnessModifier>();
                },
                EndOfCombatEffectType::TemporaryAbilityGrant => {
                    commands.entity(entity).remove::<GrantedAbility>();
                },
                // Other effect types...
            }
        }
    }
}
}

"Until Your Next Combat" Effects

Some effects last until a player's next combat phase begins:

#![allow(unused)]
fn main() {
pub fn process_until_next_combat_effects(
    mut commands: Commands,
    turn_manager: Res<TurnManager>,
    effect_query: Query<(Entity, &UntilNextCombatEffect, &Controllable)>,
) {
    // Only run during Beginning of Combat
    if turn_manager.current_phase != Phase::Combat(CombatStep::BeginningOfCombat) {
        return;
    }
    
    let active_player = turn_manager.get_active_player();
    
    // Find and remove effects that should end
    for (entity, effect, controllable) in effect_query.iter() {
        if controllable.controller == active_player {
            commands.entity(entity).remove::<UntilNextCombatEffect>();
            
            // Apply any cleanup logic specific to this effect
            match effect.effect_type {
                // Implementation details...
                _ => {}
            }
        }
    }
}
}

Testing Strategy

Unit Tests

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_beginning_of_combat_triggers() {
        let mut app = App::new();
        app.add_systems(Update, beginning_of_combat_triggers);
        app.init_resource::<AbilityTriggerQueue>();
        
        // Create a simple trigger
        let trigger_entity = app.world.spawn((
            AbilityTrigger {
                condition: TriggerCondition::BeginningOfCombat { controller_only: false },
                effect: TriggeredEffect::DrawCard { count: 1 },
            },
        )).id();
        
        // Set up turn manager with Beginning of Combat phase
        let mut turn_manager = TurnManager::default();
        turn_manager.current_phase = Phase::Combat(CombatStep::BeginningOfCombat);
        app.insert_resource(turn_manager);
        
        // Run the system
        app.update();
        
        // Check if trigger was added to queue
        let ability_triggers = app.world.resource::<AbilityTriggerQueue>();
        assert_eq!(ability_triggers.queue.len(), 1);
        
        let trigger_event = ability_triggers.queue.front().unwrap();
        assert_eq!(trigger_event.source, trigger_entity);
    }
    
    #[test]
    fn test_beginning_of_combat_system_phase_progression() {
        let mut app = App::new();
        app.add_systems(Update, beginning_of_combat_system);
        app.add_event::<GameEvent>();
        app.init_resource::<PrioritySystem>();
        app.init_resource::<NextState<Phase>>();
        
        // Set up active player
        let active_player = app.world.spawn((Player::default(), ActivePlayer)).id();
        
        // Set up turn manager with Beginning of Combat phase
        let mut turn_manager = TurnManager::default();
        turn_manager.current_phase = Phase::Combat(CombatStep::BeginningOfCombat);
        app.insert_resource(turn_manager);
        
        // Set up priority system to indicate all players have passed
        let mut priority_system = PrioritySystem::default();
        priority_system.priority_given = true;
        priority_system.current_player_index = 0;
        priority_system.all_passed = true;
        priority_system.stack_changed = false;
        app.insert_resource(priority_system);
        
        // Run the system
        app.update();
        
        // Check that phase advanced to Declare Attackers
        let next_phase = app.world.resource::<NextState<Phase>>();
        assert_eq!(next_phase.0, Some(Phase::Combat(CombatStep::DeclareAttackers)));
    }
    
    // Additional unit tests...
}
}

Integration Tests

#![allow(unused)]
fn main() {
#[cfg(test)]
mod integration_tests {
    use super::*;
    
    #[test]
    fn test_beginning_of_combat_workflow() {
        let mut app = App::new();
        
        // Add all relevant systems
        app.add_systems(Update, (
            beginning_of_combat_system,
            beginning_of_combat_triggers,
            evaluate_combat_static_abilities,
            process_until_next_combat_effects,
            clear_end_of_combat_effects,
        ));
        
        // Set up game state
        // Implementation details omitted for brevity
        
        // Run several updates to simulate entire beginning of combat step
        for _ in 0..5 {
            app.update();
        }
        
        // Verify that all systems executed correctly
        // Implementation details omitted for brevity
    }
    
    // Additional integration tests...
}
}

UI Considerations

During the Beginning of Combat step, the user interface should:

1. Clearly indicate the current phase (Beginning of Combat)
2. Show which player has priority
3. Highlight creatures that could potentially attack
4. Display any relevant triggered abilities that are waiting to go on the stack

This can be implemented with the following system:

#![allow(unused)]
fn main() {
pub fn update_beginning_of_combat_ui(
    turn_manager: Res<TurnManager>,
    priority_system: Res<PrioritySystem>,
    creature_query: Query<(Entity, &Creature, &Controllable)>,
    ability_triggers: Res<AbilityTriggerQueue>,
    mut ui_state: ResMut<UiState>,
) {
    // Only run during Beginning of Combat
    if turn_manager.current_phase != Phase::Combat(CombatStep::BeginningOfCombat) {
        return;
    }
    
    // Update phase display
    ui_state.current_phase_text = "Beginning of Combat".to_string();
    
    // Show player with priority
    ui_state.player_with_priority = priority_system.get_player_with_priority();
    
    // Highlight potential attackers
    let active_player = turn_manager.get_active_player();
    for (entity, creature, controllable) in creature_query.iter() {
        if controllable.controller == active_player && creature.can_attack() {
            ui_state.potential_attackers.insert(entity);
        }
    }
    
    // Display waiting triggers
    ui_state.pending_triggers = ability_triggers.queue.iter()
        .map(|trigger| (trigger.source, trigger.trigger.clone()))
        .collect();
}
}

Performance Considerations

The Beginning of Combat step generally has fewer performance implications than subsequent combat steps, but we should still be mindful of:

1. Efficiently processing "beginning of combat" triggers, which could be numerous
2. Minimizing component queries by combining related operations
3. Only performing combat-specific calculations once per beginning of combat step

Conclusion

The Beginning of Combat step, while often quickly passed through in many games, serves a crucial role in the overall combat structure. It provides the last opportunity for players to act before attackers are declared, and it's the time when many powerful combat-related triggered abilities occur. A robust implementation of this step ensures that all cards function correctly and players have appropriate opportunities to respond before the action of combat truly begins.

Declare Attackers Step

Overview

The Declare Attackers step is where the active player selects which creatures will attack and which opponents or planeswalkers they will target. In Commander, this step is particularly complex due to the multiplayer nature of the format, allowing attacks against different opponents simultaneously. This document details the implementation of the Declare Attackers step in our game engine.

Core Implementation

Phase Structure

The Declare Attackers step follows the Beginning of Combat step in the combat phase sequence:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CombatStep {
    BeginningOfCombat,
    DeclareAttackers,
    DeclareBlockers,
    CombatDamage,
    EndOfCombat,
}
}

Declare Attackers System

The core system that handles the Declare Attackers step:

#![allow(unused)]
fn main() {
pub fn declare_attackers_system(
    mut commands: Commands,
    turn_manager: Res<TurnManager>,
    mut game_events: EventWriter<GameEvent>,
    mut next_phase: ResMut<NextState<Phase>>,
    mut priority_system: ResMut<PrioritySystem>,
    mut combat_system: ResMut<CombatSystem>,
    mut attack_declarations: EventReader<AttackDeclarationEvent>,
) {
    // Only run during Declare Attackers step
    if turn_manager.current_phase != Phase::Combat(CombatStep::DeclareAttackers) {
        return;
    }

    // If this is the first time entering the step
    if !priority_system.priority_given {
        // Emit Declare Attackers event
        let active_player = turn_manager.get_active_player();
        game_events.send(GameEvent::DeclareAttackersStep {
            player: active_player,
        });
        
        // Process attack requirements and restrictions
        commands.run_system(process_attack_requirements);
        
        // Grant priority to active player for attack declarations
        priority_system.grant_initial_priority();
    }
    
    // Process any attack declarations
    for event in attack_declarations.iter() {
        process_attack_declaration(&mut combat_system, event, &mut game_events);
    }
    
    // If active player has passed priority with attack declarations finalized
    if priority_system.active_player_passed && combat_system.attack_declarations_finalized {
        // Process post-declaration triggers
        commands.run_system(process_attack_triggers);
        
        // Reset priority for all players to respond to attacks
        priority_system.reset_with_active_player_priority();
    }
    
    // If all players have passed priority and the stack is empty
    if priority_system.all_players_passed() && priority_system.stack.is_empty() {
        // If at least one attacker was declared
        if !combat_system.attackers.is_empty() {
            // Proceed to Declare Blockers step
            next_phase.set(Phase::Combat(CombatStep::DeclareBlockers));
        } else {
            // Skip to End of Combat if no attackers
            next_phase.set(Phase::Combat(CombatStep::EndOfCombat));
        }
        priority_system.priority_given = false;
    }
}

// Helper function to process an attack declaration
fn process_attack_declaration(
    combat_system: &mut CombatSystem,
    event: &AttackDeclarationEvent,
    game_events: &mut EventWriter<GameEvent>,
) {
    let AttackDeclarationEvent { attacker, defender } = event;
    
    // Validate attack declaration
    if let Some(reason) = validate_attack(*attacker, *defender, combat_system) {
        game_events.send(GameEvent::InvalidAttackDeclaration {
            attacker: *attacker,
            defender: *defender,
            reason,
        });
        return;
    }
    
    // Record the attack in the combat system
    combat_system.attackers.insert(*attacker, AttackData {
        attacker: *attacker,
        defender: *defender,
        is_commander: false, // Will be updated by a separate system
        requirements: Vec::new(),
        restrictions: Vec::new(),
    });
    
    // Emit attack declaration event
    game_events.send(GameEvent::AttackDeclared {
        attacker: *attacker,
        defender: *defender,
    });
}
}

Attack Validation

Attacks must be validated according to various rules and restrictions:

#![allow(unused)]
fn main() {
fn validate_attack(
    attacker: Entity,
    defender: Entity,
    combat_system: &CombatSystem,
) -> Option<String> {
    // Check if creature is able to attack
    if let Some(restrictions) = combat_system.attack_restrictions.get(&attacker) {
        for restriction in restrictions {
            match restriction {
                AttackRestriction::CantAttack => {
                    return Some("Creature cannot attack".to_string());
                },
                AttackRestriction::CantAttackPlayer(player) => {
                    if *player == defender {
                        return Some("Creature cannot attack this player".to_string());
                    }
                },
                AttackRestriction::CantAttackThisTurn => {
                    return Some("Creature cannot attack this turn".to_string());
                },
                // Other restrictions...
            }
        }
    }
    
    // Check defender-specific restrictions
    if let Some(restrictions) = combat_system.defender_restrictions.get(&defender) {
        for restriction in restrictions {
            match restriction {
                DefenderRestriction::CantBeAttacked => {
                    return Some("This player or planeswalker cannot be attacked".to_string());
                },
                DefenderRestriction::CantBeAttackedBy(condition) => {
                    if condition.matches(attacker) {
                        return Some("This creature cannot attack this defender".to_string());
                    }
                },
                // Other restrictions...
            }
        }
    }
    
    // All checks passed
    None
}
}

Attack Requirements

Some creatures have requirements that dictate how they must attack:

#![allow(unused)]
fn main() {
pub fn process_attack_requirements(
    mut combat_system: ResMut<CombatSystem>,
    creature_query: Query<(Entity, &Creature, &Controllable)>,
    active_player_query: Query<Entity, With<ActivePlayer>>,
    mut game_events: EventWriter<GameEvent>,
) {
    let active_player = active_player_query.single();
    
    // Process creatures with attack requirements
    for (entity, creature, controllable) in creature_query.iter() {
        // Only check creatures controlled by active player
        if controllable.controller != active_player {
            continue;
        }
        
        // Check if creature has attack requirements
        if let Some(requirements) = combat_system.attack_requirements.get(&entity) {
            for requirement in requirements {
                match requirement {
                    AttackRequirement::MustAttack => {
                        // Creature must attack if able
                        combat_system.add_required_attacker(entity);
                        
                        game_events.send(GameEvent::AttackRequirement {
                            creature: entity,
                            requirement: "Must attack if able".to_string(),
                        });
                    },
                    AttackRequirement::MustAttackSpecificPlayer(player) => {
                        // Creature must attack a specific player
                        combat_system.add_required_attacker(entity);
                        combat_system.add_required_defender(*player, entity);
                        
                        game_events.send(GameEvent::AttackRequirement {
                            creature: entity,
                            requirement: format!("Must attack player {:?} if able", player),
                        });
                    },
                    // Other requirements...
                }
            }
        }
    }
}
}

Multiplayer Considerations

In Commander, the active player can attack multiple opponents in the same combat phase:

#![allow(unused)]
fn main() {
pub fn validate_multiplayer_attacks(
    combat_system: Res<CombatSystem>,
    turn_manager: Res<TurnManager>,
    player_query: Query<(Entity, &Player)>,
    mut game_events: EventWriter<GameEvent>,
) {
    let active_player = turn_manager.get_active_player();
    
    // Group attacks by defender
    let mut attacks_by_defender: HashMap<Entity, Vec<Entity>> = HashMap::new();
    
    for (attacker, attack_data) in &combat_system.attackers {
        attacks_by_defender.entry(attack_data.defender)
            .or_insert_with(Vec::new)
            .push(*attacker);
    }
    
    // Verify all defenders are opponents
    for (defender, attackers) in &attacks_by_defender {
        // Skip planeswalkers (they're handled separately)
        if let Ok((_, player)) = player_query.get(*defender) {
            // Verify defender is not the active player
            if *defender == active_player {
                game_events.send(GameEvent::InvalidAttackTarget {
                    attacker: attackers[0], // Just report one of the attackers
                    defender: *defender,
                    reason: "Cannot attack yourself".to_string(),
                });
            }
        }
    }
    
    // Log all attack declarations for game history
    game_events.send(GameEvent::MultiplayerAttacksDeclared {
        active_player,
        attacks_by_defender: attacks_by_defender.clone(),
    });
}
}

Commander-Specific Implementations

Commander Attack Tracking

When a commander attacks, it needs to be specially tracked for commander damage:

#![allow(unused)]
fn main() {
pub fn track_commander_attacks(
    mut combat_system: ResMut<CombatSystem>,
    commander_query: Query<Entity, With<Commander>>,
) {
    // Find all commanders that are attacking
    for (attacker, attack_data) in combat_system.attackers.iter_mut() {
        if commander_query.contains(*attacker) {
            attack_data.is_commander = true;
        }
    }
}
}

Goad Implementation

Goad is a Commander-specific mechanic that forces creatures to attack:

#![allow(unused)]
fn main() {
#[derive(Component)]
pub struct Goaded {
    pub source: Entity,
    pub until_end_of_turn: bool,
}

pub fn apply_goad_requirements(
    mut combat_system: ResMut<CombatSystem>,
    goaded_query: Query<(Entity, &Goaded, &Controllable)>,
    turn_manager: Res<TurnManager>,
) {
    let active_player = turn_manager.get_active_player();
    
    // Find all goaded creatures controlled by the active player
    for (entity, goaded, controllable) in goaded_query.iter() {
        if controllable.controller == active_player {
            // Add attack requirement - must attack if able
            combat_system.add_attack_requirement(entity, AttackRequirement::MustAttack);
            
            // Add attack restriction - can't attack the goad source
            combat_system.add_attack_restriction(entity, AttackRestriction::CantAttackPlayer(goaded.source));
        }
    }
}
}

Triggered Abilities

Attack Triggers

When attackers are declared, various triggered abilities might occur:

#![allow(unused)]
fn main() {
pub fn process_attack_triggers(
    turn_manager: Res<TurnManager>,
    combat_system: Res<CombatSystem>,
    mut ability_triggers: ResMut<AbilityTriggerQueue>,
    trigger_sources: Query<(Entity, &AbilityTrigger, &Controllable)>,
) {
    // Process "when this creature attacks" triggers
    for (attacker, _) in combat_system.attackers.iter() {
        if let Ok((entity, trigger, _)) = trigger_sources.get(*attacker) {
            if let TriggerCondition::WhenAttacks = trigger.condition {
                ability_triggers.queue.push_back(AbilityTriggerEvent {
                    source: entity,
                    trigger: trigger.clone(),
                    targets: Vec::new(),
                });
            }
        }
    }
    
    // Process "whenever a creature attacks" triggers
    for (entity, trigger, controllable) in trigger_sources.iter() {
        if let TriggerCondition::WheneverCreatureAttacks { controller_only } = trigger.condition {
            // Only consider triggers that should fire based on controller
            let should_trigger = if controller_only {
                // Check if any of the attacking creatures are controlled by this trigger's controller
                combat_system.attackers.iter().any(|(_, attack_data)| {
                    // Simplified for brevity, actual implementation would check creature controllers
                    true
                })
            } else {
                // Trigger for any attacking creature
                !combat_system.attackers.is_empty()
            };
            
            if should_trigger {
                ability_triggers.queue.push_back(AbilityTriggerEvent {
                    source: entity,
                    trigger: trigger.clone(),
                    targets: Vec::new(),
                });
            }
        }
    }
}
}

Exert Mechanic

Exert is a mechanic that gives benefits in exchange for the creature not untapping:

#![allow(unused)]
fn main() {
#[derive(Component)]
pub struct Exert {
    pub duration: ExertDuration,
    pub effect: ExertEffect,
}

pub enum ExertDuration {
    NextUntapStep,
    NextUntapStepController,
}

pub fn handle_exert_choices(
    mut commands: Commands,
    mut exert_choices: EventReader<ExertChoiceEvent>,
    mut game_events: EventWriter<GameEvent>,
) {
    for event in exert_choices.iter() {
        let ExertChoiceEvent { creature, exert } = event;
        
        if *exert {
            // Mark the creature as exerted
            commands.entity(*creature).insert(Exerted {
                until_next_untap_step: true,
            });
            
            // Apply exert effect
            // Implementation details omitted
            
            game_events.send(GameEvent::CreatureExerted {
                creature: *creature,
            });
        }
    }
}
}

State Tracking

Once all attackers are declared, we need to update the game state:

#![allow(unused)]
fn main() {
pub fn update_creature_state_on_attack(
    mut commands: Commands,
    combat_system: Res<CombatSystem>,
    mut creature_query: Query<(Entity, &mut Creature)>,
) {
    // Update all attacking creatures
    for (attacker, attack_data) in combat_system.attackers.iter() {
        if let Ok((_, mut creature)) = creature_query.get_mut(*attacker) {
            // Mark creature as attacking
            creature.attacking = Some(attack_data.defender);
            
            // Add the Attacking component for faster queries
            commands.entity(*attacker).insert(Attacking {
                defender: attack_data.defender,
            });
            
            // Tap the creature unless it has vigilance
            if !creature.has_ability(CreatureAbility::Vigilance) {
                commands.entity(*attacker).insert(Tapped(true));
            }
        }
    }
}
}

Edge Cases and Special Interactions

Attack Redirection Effects

Some effects can redirect attacks to different players or planeswalkers:

#![allow(unused)]
fn main() {
pub fn handle_attack_redirection(
    mut combat_system: ResMut<CombatSystem>,
    redirection_effects: Query<(Entity, &AttackRedirection)>,
    mut game_events: EventWriter<GameEvent>,
) {
    // Process any attack redirection effects
    let redirections: Vec<(Entity, Entity, Entity)> = combat_system.attackers
        .iter()
        .filter_map(|(attacker, attack_data)| {
            for (effect_entity, redirection) in redirection_effects.iter() {
                if redirection.original_defender == attack_data.defender 
                   && redirection.applies_to(*attacker) {
                    return Some((*attacker, attack_data.defender, redirection.new_defender));
                }
            }
            None
        })
        .collect();
    
    // Apply redirections
    for (attacker, original_defender, new_defender) in redirections {
        if let Some(attack_data) = combat_system.attackers.get_mut(&attacker) {
            // Log the redirection
            game_events.send(GameEvent::AttackRedirected {
                attacker,
                original_defender,
                new_defender,
            });
            
            // Update the attack target
            attack_data.defender = new_defender;
        }
    }
}
}

Attack Cost Effects

Some effects add costs to attacking:

#![allow(unused)]
fn main() {
pub fn handle_attack_costs(
    mut commands: Commands,
    mut combat_system: ResMut<CombatSystem>,
    cost_effects: Query<(Entity, &AttackCost)>,
    mut game_events: EventWriter<GameEvent>,
    mut mana_events: EventWriter<ManaPaymentEvent>,
) {
    // Process any attack cost effects
    let costs: Vec<(Entity, Entity, AttackCostType)> = combat_system.attackers
        .iter()
        .filter_map(|(attacker, attack_data)| {
            for (effect_entity, cost) in cost_effects.iter() {
                if cost.applies_to(*attacker, attack_data.defender) {
                    return Some((*attacker, effect_entity, cost.cost_type.clone()));
                }
            }
            None
        })
        .collect();
    
    // Apply costs
    for (attacker, cost_source, cost_type) in costs {
        match cost_type {
            AttackCostType::Mana(cost) => {
                // Request mana payment
                mana_events.send(ManaPaymentEvent {
                    source: attacker,
                    reason: PaymentReason::AttackCost { creature: attacker },
                    cost,
                });
            },
            AttackCostType::Life(amount) => {
                // Implementation for life payment
                // Details omitted
            },
            // Other cost types...
        }
        
        game_events.send(GameEvent::AttackCostApplied {
            attacker,
            cost_source,
            cost_description: format!("{:?}", cost_type),
        });
    }
}
}

Testing Strategy

Unit Tests

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_attack_validation() {
        // Test with a creature that can attack
        let result = validate_attack(
            /* mock entities and combat system */
            Entity::from_raw(1),
            Entity::from_raw(2),
            &CombatSystem::default(),
        );
        assert_eq!(result, None, "Valid attack should return None");
        
        // Test with a creature that can't attack
        let mut combat_system = CombatSystem::default();
        combat_system.add_attack_restriction(
            Entity::from_raw(1),
            AttackRestriction::CantAttack,
        );
        
        let result = validate_attack(
            Entity::from_raw(1),
            Entity::from_raw(2),
            &combat_system,
        );
        assert!(result.is_some(), "Invalid attack should return an error message");
    }
    
    #[test]
    fn test_commander_attack_tracking() {
        let mut app = App::new();
        app.add_systems(Update, track_commander_attacks);
        
        // Set up a commander and a regular creature
        let commander = app.world.spawn((Creature::default(), Commander)).id();
        let regular_creature = app.world.spawn(Creature::default()).id();
        
        // Set up combat system with both attacking
        let mut combat_system = CombatSystem::default();
        combat_system.attackers.insert(commander, AttackData {
            attacker: commander,
            defender: Entity::from_raw(3),
            is_commander: false, // Should be updated by system
            requirements: Vec::new(),
            restrictions: Vec::new(),
        });
        combat_system.attackers.insert(regular_creature, AttackData {
            attacker: regular_creature,
            defender: Entity::from_raw(3),
            is_commander: false,
            requirements: Vec::new(),
            restrictions: Vec::new(),
        });
        app.insert_resource(combat_system);
        
        // Run the system
        app.update();
        
        // Check commander status
        let combat_system = app.world.resource::<CombatSystem>();
        assert!(combat_system.attackers[&commander].is_commander, "Commander should be marked as such when attacking");
        assert!(!combat_system.attackers[&regular_creature].is_commander, "Regular creature should not be marked as a commander");
    }
    
    #[test]
    fn test_goad_mechanic() {
        let mut app = App::new();
        app.add_systems(Update, apply_goad_requirements);
        
        // Set up test environment with a goaded creature
        let active_player = app.world.spawn(Player::default()).id();
        let opponent = app.world.spawn(Player::default()).id();
        
        let goaded_creature = app.world.spawn((
            Creature::default(),
            Controllable { controller: active_player },
            Goaded { source: opponent, until_end_of_turn: true },
        )).id();
        
        // Set up turn manager
        let mut turn_manager = TurnManager::default();
        turn_manager.active_player_index = 0;
        turn_manager.player_order = vec![active_player, opponent];
        app.insert_resource(turn_manager);
        
        // Set up combat system
        let combat_system = CombatSystem::default();
        app.insert_resource(combat_system);
        
        // Run the system
        app.update();
        
        // Check results
        let combat_system = app.world.resource::<CombatSystem>();
        
        // Goaded creature should be required to attack
        let has_must_attack = combat_system.attack_requirements.get(&goaded_creature)
            .map_or(false, |reqs| reqs.iter().any(|req| matches!(req, AttackRequirement::MustAttack)));
        assert!(has_must_attack, "Goaded creature should have MustAttack requirement");
        
        // Goaded creature should not be able to attack the goad source
        let has_cant_attack_source = combat_system.attack_restrictions.get(&goaded_creature)
            .map_or(false, |reqs| reqs.iter().any(|req| matches!(req, AttackRestriction::CantAttackPlayer(p) if *p == opponent)));
        assert!(has_cant_attack_source, "Goaded creature should not be able to attack goad source");
    }
    
    // Additional unit tests...
}
}

Integration Tests

#![allow(unused)]
fn main() {
#[cfg(test)]
mod integration_tests {
    use super::*;
    
    #[test]
    fn test_declare_attackers_workflow() {
        let mut app = App::new();
        
        // Add all relevant systems
        app.add_systems(Update, (
            declare_attackers_system,
            process_attack_requirements,
            track_commander_attacks,
            process_attack_triggers,
            update_creature_state_on_attack,
        ));
        
        // Set up game state with players and creatures
        // Implementation details omitted for brevity
        
        // Simulate player declaring attackers
        app.world.resource_mut::<Events<AttackDeclarationEvent>>().send(
            AttackDeclarationEvent {
                attacker: Entity::from_raw(1),
                defender: Entity::from_raw(2),
            }
        );
        
        // Run update to process declarations
        app.update();
        
        // Verify attackers are properly recorded and state is updated
        // Implementation details omitted for brevity
    }
    
    #[test]
    fn test_multiplayer_attack_declarations() {
        let mut app = App::new();
        
        // Set up a multiplayer environment with three players
        let active_player = app.world.spawn(Player::default()).id();
        let opponent1 = app.world.spawn(Player::default()).id();
        let opponent2 = app.world.spawn(Player::default()).id();
        
        // Set up creatures for the active player
        let creature1 = app.world.spawn(Creature::default()).id();
        let creature2 = app.world.spawn(Creature::default()).id();
        
        // Set up turn manager
        let mut turn_manager = TurnManager::default();
        turn_manager.active_player_index = 0;
        turn_manager.player_order = vec![active_player, opponent1, opponent2];
        app.insert_resource(turn_manager);
        
        // Set up combat system with attacks against different opponents
        let mut combat_system = CombatSystem::default();
        combat_system.attackers.insert(creature1, AttackData {
            attacker: creature1,
            defender: opponent1,
            is_commander: false,
            requirements: Vec::new(),
            restrictions: Vec::new(),
        });
        combat_system.attackers.insert(creature2, AttackData {
            attacker: creature2,
            defender: opponent2,
            is_commander: false,
            requirements: Vec::new(),
            restrictions: Vec::new(),
        });
        app.insert_resource(combat_system);
        
        // Add validate_multiplayer_attacks system
        app.add_systems(Update, validate_multiplayer_attacks);
        app.add_event::<GameEvent>();
        
        // Run the system
        app.update();
        
        // Check for multiplayer attack event
        let mut found_event = false;
        let events = app.world.resource::<Events<GameEvent>>();
        let mut reader = events.get_reader();
        
        for event in reader.iter(events) {
            if let GameEvent::MultiplayerAttacksDeclared { .. } = event {
                found_event = true;
                break;
            }
        }
        
        assert!(found_event, "Multiplayer attack event should be emitted");
    }
    
    // Additional integration tests...
}
}

UI Considerations

The UI during the Declare Attackers step needs to clearly communicate various states:

#![allow(unused)]
fn main() {
pub fn update_declare_attackers_ui(
    turn_manager: Res<TurnManager>,
    combat_system: Res<CombatSystem>,
    creature_query: Query<(Entity, &Creature, &Controllable)>,
    player_query: Query<Entity, With<Player>>,
    mut ui_state: ResMut<UiState>,
) {
    // Only run during Declare Attackers step
    if turn_manager.current_phase != Phase::Combat(CombatStep::DeclareAttackers) {
        return;
    }
    
    // Update phase display
    ui_state.current_phase_text = "Declare Attackers".to_string();
    
    // Get active player
    let active_player = turn_manager.get_active_player();
    
    // Highlight potential attackers
    ui_state.potential_attackers.clear();
    for (entity, creature, controllable) in creature_query.iter() {
        if controllable.controller == active_player && creature.can_attack() {
            ui_state.potential_attackers.insert(entity);
            
            // Mark creatures that must attack
            if let Some(requirements) = combat_system.attack_requirements.get(&entity) {
                if requirements.iter().any(|req| matches!(req, AttackRequirement::MustAttack)) {
                    ui_state.creatures_with_requirements.insert(entity, "Must attack if able".to_string());
                }
            }
        }
    }
    
    // Highlight potential defenders
    ui_state.potential_defenders.clear();
    for entity in player_query.iter() {
        if entity != active_player {
            ui_state.potential_defenders.insert(entity);
        }
    }
    
    // Show current attack declarations
    ui_state.current_attacks.clear();
    for (attacker, attack_data) in combat_system.attackers.iter() {
        ui_state.current_attacks.insert(*attacker, attack_data.defender);
    }
}
}

Performance Considerations

1. Efficient Attack Validation: The validation of attacks should be optimized to avoid redundant checks.

2. Caching Attack Results: Once attack declarations are finalized, the results can be cached for use in subsequent steps.

3. Parallel Processing: For games with many attackers, processing attack triggers could be done in parallel.

4. Minimize Component Access: Group related queries to minimize entity access operations.

Conclusion

The Declare Attackers step is a critical part of the combat phase in Commander. A robust implementation ensures that all game rules are properly enforced, including multiplayer-specific mechanics like Goad. By handling attack declarations, restrictions, requirements, and triggers correctly, we provide the foundation for a smooth and accurate combat resolution process.

Declare Blockers Step

Overview

The Declare Blockers step is the phase of combat where defending players assign their creatures to block attacking creatures. In Commander, this step can be particularly complex due to the multiplayer nature of the format, where multiple players may be defending against attacks simultaneously. This document outlines the implementation of the Declare Blockers step in our game engine.

Core Implementation

Phase Structure

The Declare Blockers step follows the Declare Attackers step in the combat phase sequence:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CombatStep {
    BeginningOfCombat,
    DeclareAttackers,
    DeclareBlockers,
    CombatDamage,
    EndOfCombat,
}
}

Declare Blockers System

The core system that handles the Declare Blockers step:

#![allow(unused)]
fn main() {
pub fn declare_blockers_system(
    mut commands: Commands,
    turn_manager: Res<TurnManager>,
    mut game_events: EventWriter<GameEvent>,
    mut next_phase: ResMut<NextState<Phase>>,
    mut priority_system: ResMut<PrioritySystem>,
    combat_system: Res<CombatSystem>,
    mut block_declarations: EventReader<BlockDeclarationEvent>,
) {
    // Only run during Declare Blockers step
    if turn_manager.current_phase != Phase::Combat(CombatStep::DeclareBlockers) {
        return;
    }

    // If this is the first time entering the step
    if !priority_system.priority_given {
        // Emit Declare Blockers event
        game_events.send(GameEvent::DeclareBlockersStep);
        
        // Process block requirements and restrictions
        commands.run_system(process_block_requirements);
        
        // Create turn order for block declarations
        priority_system.set_player_order_for_blockers(combat_system.attacked_players());
        
        // Grant priority to first defending player
        priority_system.grant_initial_priority();
    }
    
    // Process any block declarations
    for event in block_declarations.iter() {
        process_block_declaration(&mut commands, event, &combat_system, &mut game_events);
    }
    
    // If all defending players have passed priority with block declarations finalized
    if priority_system.all_defenders_passed && combat_system.block_declarations_finalized {
        // Process post-declaration triggers
        commands.run_system(process_block_triggers);
        
        // Reset priority for all players to respond to blocks
        priority_system.reset_with_active_player_priority();
    }
    
    // If all players have passed priority and the stack is empty
    if priority_system.all_players_passed() && priority_system.stack.is_empty() {
        // Proceed to Combat Damage step
        next_phase.set(Phase::Combat(CombatStep::CombatDamage));
        priority_system.priority_given = false;
    }
}

// Helper function to process a block declaration
fn process_block_declaration(
    commands: &mut Commands,
    event: &BlockDeclarationEvent,
    combat_system: &CombatSystem,
    game_events: &mut EventWriter<GameEvent>,
) {
    let BlockDeclarationEvent { blocker, attackers } = event;
    
    // Validate block declaration
    if let Some(reason) = validate_block(*blocker, attackers, combat_system) {
        game_events.send(GameEvent::InvalidBlockDeclaration {
            blocker: *blocker,
            attackers: attackers.clone(),
            reason,
        });
        return;
    }
    
    // Record the block in the combat system
    commands.entity(*blocker).insert(Blocking {
        blocked_attackers: attackers.clone(),
    });
    
    // Emit block declaration event
    for attacker in attackers {
        game_events.send(GameEvent::BlockDeclared {
            blocker: *blocker,
            attacker: *attacker,
        });
    }
}
}

Block Validation

Blocks must be validated according to various rules and restrictions:

#![allow(unused)]
fn main() {
fn validate_block(
    blocker: Entity,
    attackers: &[Entity],
    combat_system: &CombatSystem,
) -> Option<String> {
    // Check if creature can block at all
    if let Some(restrictions) = combat_system.block_restrictions.get(&blocker) {
        for restriction in restrictions {
            match restriction {
                BlockRestriction::CantBlock => {
                    return Some("Creature cannot block".to_string());
                },
                // Other general block restrictions...
            }
        }
    }
    
    // Check if creature can block multiple attackers
    if attackers.len() > 1 {
        let can_block_multiple = check_can_block_multiple(blocker, combat_system);
        if !can_block_multiple {
            return Some("Creature cannot block multiple attackers".to_string());
        }
    }
    
    // Check attacker-specific restrictions
    for attacker in attackers {
        // Check if this attacker can be blocked by this blocker
        if let Some(restrictions) = combat_system.attacker_restrictions.get(attacker) {
            for restriction in restrictions {
                match restriction {
                    AttackerRestriction::CantBeBlocked => {
                        return Some(format!("Attacker {} cannot be blocked", attacker.index()));
                    },
                    AttackerRestriction::CantBeBlockedBy(condition) => {
                        if condition.matches(blocker) {
                            return Some(format!("Attacker {} cannot be blocked by this creature", attacker.index()));
                        }
                    },
                    // Other attacker-specific restrictions...
                }
            }
        }
    }
    
    // Check special blocking requirements
    if let Some(requirements) = combat_system.attacker_block_requirements.get(&attackers[0]) {
        for requirement in requirements {
            match requirement {
                BlockRequirement::MustBeBlockedByAtLeast(count) => {
                    if combat_system.get_blockers_for_attacker(attackers[0]).len() + 1 < *count {
                        // This single blocker is not enough to satisfy the requirement
                        // Note: In a real implementation, this would need to check if the requirement
                        // could be satisfied with other declared blocks
                        return Some(format!("Attacker requires at least {} blockers", count));
                    }
                },
                // Other block requirements...
            }
        }
    }
    
    // All checks passed
    None
}

// Helper function to check if a creature can block multiple attackers
fn check_can_block_multiple(
    blocker: Entity,
    combat_system: &CombatSystem,
) -> bool {
    // Check if creature has a special ability that allows blocking multiple attackers
    if let Some(special_abilities) = combat_system.creature_special_abilities.get(&blocker) {
        if special_abilities.contains(&SpecialAbility::CanBlockAdditionalCreature(1)) {
            return true;
        }
        if special_abilities.contains(&SpecialAbility::CanBlockAnyNumber) {
            return true;
        }
    }
    
    // By default, creatures can only block one attacker
    false
}
}

Block Requirements

Some effects in the game can force creatures to block:

#![allow(unused)]
fn main() {
pub fn process_block_requirements(
    combat_system: Res<CombatSystem>,
    mut game_events: EventWriter<GameEvent>,
    creature_query: Query<(Entity, &Creature, &Controllable)>,
    player_query: Query<(Entity, &Player)>,
) {
    // Identify all players who are being attacked
    let attacked_players: HashSet<Entity> = combat_system.attackers
        .iter()
        .filter_map(|(_, attack_data)| {
            if player_query.contains(attack_data.defender) {
                Some(attack_data.defender)
            } else {
                None
            }
        })
        .collect();
    
    // Process creatures with block requirements
    for (entity, creature, controllable) in creature_query.iter() {
        // Only check creatures controlled by players being attacked
        if !attacked_players.contains(&controllable.controller) {
            continue;
        }
        
        // Check if creature has block requirements
        if let Some(requirements) = combat_system.block_requirements.get(&entity) {
            for requirement in requirements {
                match requirement {
                    BlockRequirement::MustBlock => {
                        // Creature must block if able
                        game_events.send(GameEvent::BlockRequirement {
                            creature: entity,
                            requirement: "Must block if able".to_string(),
                        });
                    },
                    BlockRequirement::MustBlockAttacker(attacker) => {
                        // Creature must block a specific attacker
                        if combat_system.attackers.contains_key(attacker) {
                            game_events.send(GameEvent::BlockRequirement {
                                creature: entity,
                                requirement: format!("Must block attacker {:?} if able", attacker),
                            });
                        }
                    },
                    // Other requirements...
                }
            }
        }
    }
}
}

Evasion Abilities

Evasion abilities like Flying, Menace, etc. are essential to the blocking rules:

#![allow(unused)]
fn main() {
pub fn apply_evasion_restrictions(
    mut combat_system: ResMut<CombatSystem>,
    creature_query: Query<(Entity, &Creature)>,
) {
    // Process flying
    for (entity, creature) in creature_query.iter() {
        if creature.has_ability(CreatureAbility::Flying) {
            // Flying creatures can only be blocked by creatures with flying or reach
            combat_system.add_attacker_restriction(
                entity,
                AttackerRestriction::CantBeBlockedBy(BlockerCondition::NotFlyingOrReach),
            );
        }
        
        if creature.has_ability(CreatureAbility::Menace) {
            // Menace creatures must be blocked by at least two creatures
            combat_system.add_attacker_block_requirement(
                entity,
                BlockRequirement::MustBeBlockedByAtLeast(2),
            );
        }
        
        if creature.has_ability(CreatureAbility::Fear) {
            // Fear creatures can only be blocked by black or artifact creatures
            combat_system.add_attacker_restriction(
                entity,
                AttackerRestriction::CantBeBlockedBy(BlockerCondition::NotBlackOrArtifact),
            );
        }
        
        // Implement other evasion abilities
    }
}
}

Multiplayer Considerations

In multiplayer Commander games, multiple players might need to declare blockers:

#![allow(unused)]
fn main() {
pub fn handle_multiplayer_blocks(
    combat_system: Res<CombatSystem>,
    turn_manager: Res<TurnManager>,
    player_query: Query<(Entity, &Player)>,
    mut priority_system: ResMut<PrioritySystem>,
) {
    // Group attackers by defending player
    let mut attackers_by_defender: HashMap<Entity, Vec<Entity>> = HashMap::new();
    
    for (attacker, attack_data) in &combat_system.attackers {
        if player_query.contains(attack_data.defender) {
            attackers_by_defender.entry(attack_data.defender)
                .or_insert_with(Vec::new)
                .push(*attacker);
        }
    }
    
    // Set up priority for each defending player in turn order
    let mut defender_order = Vec::new();
    for player_idx in 0..turn_manager.player_order.len() {
        let player_entity = turn_manager.player_order[player_idx];
        if attackers_by_defender.contains_key(&player_entity) {
            defender_order.push(player_entity);
        }
    }
    
    // Update priority system with defender order
    priority_system.defender_order = defender_order;
}
}

Special Blocking Rules

Multiple Blockers

When a single attacker is blocked by multiple creatures:

#![allow(unused)]
fn main() {
pub fn handle_multiple_blockers(
    mut combat_system: ResMut<CombatSystem>,
    blocking_query: Query<(Entity, &Blocking)>,
    mut game_events: EventWriter<GameEvent>,
) {
    // Build a map of attackers to their blockers
    let mut blockers_by_attacker: HashMap<Entity, Vec<Entity>> = HashMap::new();
    
    for (blocker, blocking) in blocking_query.iter() {
        for attacker in &blocking.blocked_attackers {
            blockers_by_attacker.entry(*attacker)
                .or_insert_with(Vec::new)
                .push(blocker);
        }
    }
    
    // Process attackers with multiple blockers
    for (attacker, blockers) in blockers_by_attacker.iter() {
        if blockers.len() > 1 {
            // Attacker's controller declares damage assignment order
            game_events.send(GameEvent::DamageAssignmentOrderNeeded {
                attacker: *attacker,
                blockers: blockers.clone(),
            });
        }
    }
}
}

Triggered Abilities

When blockers are declared, various triggered abilities might occur:

#![allow(unused)]
fn main() {
pub fn process_block_triggers(
    combat_system: Res<CombatSystem>,
    blocking_query: Query<(Entity, &Blocking)>,
    mut ability_triggers: ResMut<AbilityTriggerQueue>,
    trigger_sources: Query<(Entity, &AbilityTrigger)>,
) {
    // Create attacker to blocker map
    let mut blockers_by_attacker: HashMap<Entity, Vec<Entity>> = HashMap::new();
    
    for (blocker, blocking) in blocking_query.iter() {
        for attacker in &blocking.blocked_attackers {
            blockers_by_attacker.entry(*attacker)
                .or_insert_with(Vec::new)
                .push(blocker);
        }
    }
    
    // Process "when this creature blocks" triggers
    for (blocker, blocking) in blocking_query.iter() {
        if let Ok((entity, trigger)) = trigger_sources.get(blocker) {
            if let TriggerCondition::WhenBlocks = trigger.condition {
                for attacker in &blocking.blocked_attackers {
                    ability_triggers.queue.push_back(AbilityTriggerEvent {
                        source: entity,
                        trigger: trigger.clone(),
                        targets: vec![*attacker], // The attacker is the target
                    });
                }
            }
        }
    }
    
    // Process "when this creature becomes blocked" triggers
    for (attacker, blockers) in blockers_by_attacker.iter() {
        if let Ok((entity, trigger)) = trigger_sources.get(*attacker) {
            if let TriggerCondition::WhenBecomesBlocked = trigger.condition {
                ability_triggers.queue.push_back(AbilityTriggerEvent {
                    source: entity,
                    trigger: trigger.clone(),
                    targets: blockers.clone(), // All blockers are targets
                });
            }
        }
    }
    
    // Process "whenever a creature blocks" triggers
    for (entity, trigger) in trigger_sources.iter() {
        if let TriggerCondition::WheneverCreatureBlocks { controller_only } = trigger.condition {
            let should_trigger = if controller_only {
                // Only trigger for creatures controlled by the same player
                // Implementation details omitted for brevity
                true
            } else {
                // Trigger for any blocking creature
                !blocking_query.is_empty()
            };
            
            if should_trigger {
                ability_triggers.queue.push_back(AbilityTriggerEvent {
                    source: entity,
                    trigger: trigger.clone(),
                    targets: Vec::new(), // No specific targets
                });
            }
        }
    }
}
}

State Tracking

Once all blockers are declared, we need to update the game state:

#![allow(unused)]
fn main() {
pub fn update_creature_state_on_block(
    mut commands: Commands,
    blocking_query: Query<(Entity, &Blocking, &mut Creature)>,
) {
    // Update all blocking creatures
    for (entity, blocking, mut creature) in blocking_query.iter_mut() {
        // Mark creature as blocking
        creature.blocking = blocking.blocked_attackers.clone();
        
        // Tap the creature if it has vigilance for blocking
        // Note: This is not a standard MTG rule but could be a house rule or special card effect
        if creature.has_ability(CreatureAbility::VigilanceForBlocking) {
            commands.entity(entity).insert(Tapped(true));
        }
    }
}
}

Edge Cases and Special Interactions

Banding

Banding is a complex ability that affects blocks:

#![allow(unused)]
fn main() {
pub fn handle_banding(
    mut combat_system: ResMut<CombatSystem>,
    creature_query: Query<(Entity, &Creature)>,
    blocking_query: Query<(Entity, &Blocking)>,
) {
    // Find all creatures with banding
    let banding_creatures: HashSet<Entity> = creature_query
        .iter()
        .filter_map(|(entity, creature)| {
            if creature.has_ability(CreatureAbility::Banding) {
                Some(entity)
            } else {
                None
            }
        })
        .collect();
    
    // Process attackers blocked by banding creatures
    let mut defenders_control_damage_assignment: HashSet<Entity> = HashSet::new();
    
    for (blocker, blocking) in blocking_query.iter() {
        if banding_creatures.contains(&blocker) {
            // If a banding creature is blocking, the defender controls damage assignment
            for attacker in &blocking.blocked_attackers {
                defenders_control_damage_assignment.insert(*attacker);
            }
        }
    }
    
    // Update combat system
    for attacker in defenders_control_damage_assignment {
        combat_system.add_attacker_flag(attacker, AttackerFlag::DefenderControlsDamageAssignment);
    }
}
}

Protection

Protection affects blocking in various ways:

#![allow(unused)]
fn main() {
pub fn apply_protection_block_restrictions(
    mut combat_system: ResMut<CombatSystem>,
    creature_query: Query<(Entity, &Creature, &Protection)>,
) {
    for (entity, _, protection) in creature_query.iter() {
        match protection.from {
            ProtectionFrom::Color(color) => {
                // Creature with protection from a color can't be blocked by creatures of that color
                combat_system.add_attacker_restriction(
                    entity,
                    AttackerRestriction::CantBeBlockedBy(BlockerCondition::HasColor(color)),
                );
                
                // Creature with protection can't block creatures of that color
                combat_system.add_block_restriction(
                    entity,
                    BlockRestriction::CantBlockCreature(AttackerCondition::HasColor(color)),
                );
            },
            ProtectionFrom::Type(card_type) => {
                // Similar restrictions for protection from a type
                // Implementation details omitted for brevity
            },
            // Other protection types...
        }
    }
}
}

Testing Strategy

Unit Tests

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_block_validation() {
        // Test with a creature that can block
        let result = validate_block(
            /* mock entities and combat system */
            Entity::from_raw(1),
            &[Entity::from_raw(2)],
            &CombatSystem::default(),
        );
        assert_eq!(result, None, "Valid block should return None");
        
        // Test with a creature that can't block
        let mut combat_system = CombatSystem::default();
        combat_system.add_block_restriction(
            Entity::from_raw(1),
            BlockRestriction::CantBlock,
        );
        
        let result = validate_block(
            Entity::from_raw(1),
            &[Entity::from_raw(2)],
            &combat_system,
        );
        assert!(result.is_some(), "Invalid block should return an error message");
    }
    
    #[test]
    fn test_flying_restriction() {
        let mut app = App::new();
        app.add_systems(Update, apply_evasion_restrictions);
        
        // Create a flying creature
        let flying_creature = app.world.spawn((
            Creature {
                abilities: vec![CreatureAbility::Flying],
                ..Default::default()
            },
        )).id();
        
        // Set up combat system
        let combat_system = CombatSystem::default();
        app.insert_resource(combat_system);
        
        // Run the system
        app.update();
        
        // Check if flying restriction was applied
        let combat_system = app.world.resource::<CombatSystem>();
        
        let has_flying_restriction = combat_system.attacker_restrictions.get(&flying_creature)
            .map_or(false, |reqs| reqs.iter().any(|req| matches!(req, AttackerRestriction::CantBeBlockedBy(BlockerCondition::NotFlyingOrReach))));
        
        assert!(has_flying_restriction, "Flying creature should have CantBeBlockedBy restriction");
    }
    
    #[test]
    fn test_multiple_blockers() {
        let mut app = App::new();
        app.add_systems(Update, handle_multiple_blockers);
        app.add_event::<GameEvent>();
        
        // Set up an attacker and multiple blockers
        let attacker = app.world.spawn(Creature::default()).id();
        let blocker1 = app.world.spawn((
            Creature::default(),
            Blocking { blocked_attackers: vec![attacker] },
        )).id();
        let blocker2 = app.world.spawn((
            Creature::default(),
            Blocking { blocked_attackers: vec![attacker] },
        )).id();
        
        // Set up combat system
        let combat_system = CombatSystem::default();
        app.insert_resource(combat_system);
        
        // Run the system
        app.update();
        
        // Check for damage assignment order event
        let mut event_reader = app.world.resource_mut::<Events<GameEvent>>();
        let mut found_event = false;
        
        for event in event_reader.iter() {
            if let GameEvent::DamageAssignmentOrderNeeded { attacker: a, blockers } = event {
                if *a == attacker && blockers.contains(&blocker1) && blockers.contains(&blocker2) {
                    found_event = true;
                    break;
                }
            }
        }
        
        assert!(found_event, "Damage assignment order event should be emitted for multiple blockers");
    }
    
    // Additional unit tests...
}
}

Integration Tests

#![allow(unused)]
fn main() {
#[cfg(test)]
mod integration_tests {
    use super::*;
    
    #[test]
    fn test_declare_blockers_workflow() {
        let mut app = App::new();
        
        // Add all relevant systems
        app.add_systems(Update, (
            declare_blockers_system,
            process_block_requirements,
            apply_evasion_restrictions,
            handle_multiple_blockers,
            process_block_triggers,
            update_creature_state_on_block,
        ));
        
        // Set up game state with attackers and defenders
        // Implementation details omitted for brevity
        
        // Simulate player declaring blockers
        app.world.resource_mut::<Events<BlockDeclarationEvent>>().send(
            BlockDeclarationEvent {
                blocker: Entity::from_raw(1),
                attackers: vec![Entity::from_raw(2)],
            }
        );
        
        // Run update to process declarations
        app.update();
        
        // Verify blockers are properly recorded and state is updated
        // Implementation details omitted for brevity
    }
    
    #[test]
    fn test_evasion_abilities_interaction() {
        let mut app = App::new();
        
        // Set up attacker with flying
        let flying_attacker = app.world.spawn((
            Creature {
                abilities: vec![CreatureAbility::Flying],
                ..Default::default()
            },
        )).id();
        
        // Set up potential blockers: one with flying, one with reach, one with neither
        let flying_blocker = app.world.spawn((
            Creature {
                abilities: vec![CreatureAbility::Flying],
                ..Default::default()
            },
        )).id();
        
        let reach_blocker = app.world.spawn((
            Creature {
                abilities: vec![CreatureAbility::Reach],
                ..Default::default()
            },
        )).id();
        
        let normal_blocker = app.world.spawn(Creature::default()).id();
        
        // Set up combat system with the attacker
        let mut combat_system = CombatSystem::default();
        combat_system.attackers.insert(flying_attacker, AttackData {
            attacker: flying_attacker,
            defender: Entity::from_raw(10), // Some player
            is_commander: false,
            requirements: Vec::new(),
            restrictions: Vec::new(),
        });
        app.insert_resource(combat_system);
        
        // Add relevant systems
        app.add_systems(Update, apply_evasion_restrictions);
        
        // Run the system
        app.update();
        
        // Try to declare blocks with each blocker
        let can_flying_block = validate_block(flying_blocker, &[flying_attacker], &app.world.resource::<CombatSystem>());
        let can_reach_block = validate_block(reach_blocker, &[flying_attacker], &app.world.resource::<CombatSystem>());
        let can_normal_block = validate_block(normal_blocker, &[flying_attacker], &app.world.resource::<CombatSystem>());
        
        // Verify results
        assert_eq!(can_flying_block, None, "Flying creature should be able to block flying attacker");
        assert_eq!(can_reach_block, None, "Reach creature should be able to block flying attacker");
        assert!(can_normal_block.is_some(), "Normal creature should not be able to block flying attacker");
    }
    
    // Additional integration tests...
}
}

UI Considerations

The UI during the Declare Blockers step needs to clearly communicate various states:

#![allow(unused)]
fn main() {
pub fn update_declare_blockers_ui(
    turn_manager: Res<TurnManager>,
    combat_system: Res<CombatSystem>,
    creature_query: Query<(Entity, &Creature, &Controllable)>,
    attacking_query: Query<Entity, With<Attacking>>,
    blocking_query: Query<(Entity, &Blocking)>,
    mut ui_state: ResMut<UiState>,
) {
    // Only run during Declare Blockers step
    if turn_manager.current_phase != Phase::Combat(CombatStep::DeclareBlockers) {
        return;
    }
    
    // Update phase display
    ui_state.current_phase_text = "Declare Blockers".to_string();
    
    // Get active player and current player with priority
    let active_player = turn_manager.get_active_player();
    let current_player = turn_manager.get_current_player();
    
    // Highlight attackers
    ui_state.attackers.clear();
    for attacker in attacking_query.iter() {
        ui_state.attackers.insert(attacker);
    }
    
    // Highlight potential blockers for current player
    ui_state.potential_blockers.clear();
    for (entity, creature, controllable) in creature_query.iter() {
        if controllable.controller == current_player && creature.can_block() {
            ui_state.potential_blockers.insert(entity);
            
            // Mark creatures that must block
            if let Some(requirements) = combat_system.block_requirements.get(&entity) {
                if requirements.iter().any(|req| matches!(req, BlockRequirement::MustBlock)) {
                    ui_state.creatures_with_requirements.insert(entity, "Must block if able".to_string());
                }
            }
        }
    }
    
    // Show current block declarations
    ui_state.current_blocks.clear();
    for (blocker, blocking) in blocking_query.iter() {
        ui_state.current_blocks.insert(blocker, blocking.blocked_attackers.clone());
    }
    
    // Highlight legal blocks
    ui_state.legal_blocks.clear();
    for attacker in attacking_query.iter() {
        let legal_blockers = creature_query
            .iter()
            .filter_map(|(entity, creature, controllable)| {
                if controllable.controller == current_player && 
                   validate_block(entity, &[attacker], &combat_system).is_none() {
                    Some(entity)
                } else {
                    None
                }
            })
            .collect::<Vec<_>>();
        
        ui_state.legal_blocks.insert(attacker, legal_blockers);
    }
}
}

Performance Considerations

1. Efficient Block Validation: The validation of blocks should be optimized to avoid redundant checks.

2. Caching Block Results: Once block declarations are finalized, the results can be cached for use in subsequent steps.

3. Minimize Entity Queries: Group related queries to minimize entity access operations.

4. Parallel Processing: For games with many blockers, processing block triggers could be done in parallel.

Conclusion

The Declare Blockers step is a critical part of the combat phase in Commander, particularly in multiplayer games where multiple players may be defending simultaneously. A robust implementation ensures that all game rules are properly enforced, including evasion abilities, protection effects, and multi-blocker scenarios. By handling block declarations, restrictions, requirements, and triggers correctly, we provide the foundation for accurate combat resolution in the following steps.

First Strike Damage

Overview

The First Strike Damage step is a conditional sub-step within the Combat Damage step that occurs when at least one creature with first strike or double strike is involved in combat. During this step, only creatures with first strike or double strike deal combat damage, while other creatures wait until the regular Combat Damage step.

This document outlines the implementation details, edge cases, and testing strategies for the First Strike Damage step in our Commander engine.

Core Concepts

First Strike Damage Flow

The First Strike Damage step follows this general flow:

1. Check if any attacking or blocking creatures have first strike or double strike
2. If yes, create a dedicated First Strike Damage step before the regular Combat Damage step
3. Only creatures with first strike or double strike assign and deal damage in this step
4. State-based actions are checked
5. Triggers from first strike damage are put on the stack
6. Priority passes to players in turn order
7. Once all players pass priority and the stack is empty, the game proceeds to the regular Combat Damage step

First Strike vs. Double Strike

The key difference between first strike and double strike:

• Creatures with first strike deal damage only during the First Strike Damage step
• Creatures with double strike deal damage in both the First Strike Damage step and the regular Combat Damage step

Implementation Design

Data Structures

#![allow(unused)]
fn main() {
// Components for first strike and double strike abilities
#[derive(Component)]
struct FirstStrike;

#[derive(Component)]
struct DoubleStrike;

// System resource for tracking the first strike step
struct FirstStrikeDamageSystem {
    triggers_processed: bool,
}
}

First Strike Checking System

#![allow(unused)]
fn main() {
fn check_for_first_strike_step(
    mut turn_manager: ResMut<TurnManager>,
    first_strike_query: Query<Entity, Or<(With<FirstStrike>, With<DoubleStrike>)>>,
    combat_participants: Query<Entity, Or<(With<Attacking>, With<Blocking>)>>
) {
    // Only check when transitioning from Declare Blockers to Combat Damage
    if !matches!(turn_manager.current_phase, Phase::Combat(CombatStep::DeclareBlockers)) {
        return;
    }
    
    // Check if any creature in combat has first strike or double strike
    let has_first_strike = combat_participants.iter().any(|entity| {
        first_strike_query.contains(entity)
    });
    
    // If there are creatures with first strike, we'll use the FirstStrike step
    if has_first_strike {
        turn_manager.next_phase = Some(Phase::Combat(CombatStep::FirstStrike));
    } else {
        turn_manager.next_phase = Some(Phase::Combat(CombatStep::CombatDamage));
    }
}
}

First Strike Damage System

#![allow(unused)]
fn main() {
fn first_strike_damage_system(
    mut commands: Commands,
    mut combat_system: ResMut<CombatSystem>,
    turn_manager: Res<TurnManager>,
    creature_query: Query<(Entity, &Creature, &Health, Option<&FirstStrike>, Option<&DoubleStrike>)>,
    attacker_query: Query<(Entity, &Attacking)>,
    blocker_query: Query<(Entity, &Blocking)>,
    player_query: Query<(Entity, &Player, &Health)>,
    mut commander_damage: Query<&mut CommanderDamage>,
    // Other system parameters
) {
    // Only run during first strike damage step
    if !matches!(turn_manager.current_phase, Phase::Combat(CombatStep::FirstStrike)) {
        return;
    }
    
    // Find creatures with first strike or double strike that are in combat
    let first_strike_creatures = creature_query
        .iter()
        .filter(|(entity, _, _, first_strike, double_strike)| {
            (first_strike.is_some() || double_strike.is_some()) &&
            (attacker_query.contains(*entity) || blocker_query.contains(*entity))
        })
        .collect::<Vec<_>>();
        
    // Assign and deal damage
    for (entity, creature, _, _, _) in first_strike_creatures {
        // Determine damage amount and recipients
        let power = creature.power;
        
        if let Ok((_, attacking)) = attacker_query.get(entity) {
            // Attacking creature deals damage
            assign_attacker_damage(
                entity, 
                power, 
                attacking.defending, 
                &blocker_query, 
                &mut combat_system
            );
        } else if let Ok((_, blocking)) = blocker_query.get(entity) {
            // Blocking creature deals damage
            assign_blocker_damage(
                entity, 
                power, 
                &blocking.blocked_attackers, 
                &mut combat_system
            );
        }
    }
    
    // Deal all assigned damage simultaneously
    process_damage_assignments(&mut commands, &combat_system, &mut commander_damage);
    
    // Check for state-based actions
    check_state_based_actions(&mut commands, &player_query, &creature_query);
    
    // Record that first strike damage has been processed
    combat_system.first_strike_round_completed = true;
}
}

Special Cases and Edge Scenarios

Gaining/Losing First Strike During Combat

Creatures might gain or lose first strike abilities during combat:

#![allow(unused)]
fn main() {
fn handle_first_strike_changes(
    mut first_strike_system: ResMut<FirstStrikeDamageSystem>,
    turn_manager: Res<TurnManager>,
    added_first_strike: Query<Entity, Added<FirstStrike>>,
    removed_first_strike: Query<Entity, Without<FirstStrike>>,
    combat_participants: Query<Entity, Or<(With<Attacking>, With<Blocking>)>>,
    was_in_combat: Local<HashSet<Entity>>
) {
    // Check if any creature in combat gained or lost first strike
    let gained_first_strike = added_first_strike.iter()
        .filter(|&entity| combat_participants.contains(entity))
        .count() > 0;
        
    let lost_first_strike = removed_first_strike.iter()
        .filter(|&entity| was_in_combat.contains(&entity))
        .count() > 0;
        
    // If changes occurred during declare blockers step, we might need to adjust
    // whether a first strike step will occur
    if matches!(turn_manager.current_phase, Phase::Combat(CombatStep::DeclareBlockers)) {
        if gained_first_strike {
            first_strike_system.needed = true;
        }
    }
    
    // Update our tracking of combat participants
    was_in_combat.clear();
    for entity in combat_participants.iter() {
        was_in_combat.insert(entity);
    }
}
}

Removing Creatures During First Strike

If a creature is destroyed by first strike damage, it doesn't deal regular combat damage:

#![allow(unused)]
fn main() {
fn track_destroyed_by_first_strike(
    combat_system: Res<CombatSystem>,
    mut destroyed_entities: ResMut<DestroyedEntities>,
    damage_events: Query<&DamageEvent>,
    creature_query: Query<&Health>
) {
    // Only track during first strike damage
    if !combat_system.first_strike_round_completed {
        return;
    }
    
    // Find creatures that received lethal damage during first strike
    for damage_event in damage_events.iter() {
        if let Ok(health) = creature_query.get(damage_event.target) {
            if health.current <= 0 {
                destroyed_entities.insert(damage_event.target);
            }
        }
    }
}
}

Fast Effect Windows

Players get priority after first strike damage, allowing them to cast spells before regular damage:

#![allow(unused)]
fn main() {
fn handle_first_strike_priority(
    mut turn_manager: ResMut<TurnManager>,
    stack: Res<Stack>,
    combat_system: Res<CombatSystem>
) {
    // Only handle during first strike step
    if !matches!(turn_manager.current_phase, Phase::Combat(CombatStep::FirstStrike)) {
        return;
    }
    
    // If first strike damage has been dealt and the stack is empty,
    // we can proceed to regular combat damage
    if combat_system.first_strike_round_completed && stack.is_empty() {
        turn_manager.advance_phase();
    }
}
}

Testing Strategy

Unit Tests

#![allow(unused)]
fn main() {
#[test]
fn test_first_strike_damage() {
    // Set up test world
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, first_strike_damage_system);
       
    // Create attacker with first strike
    let attacker = app.world.spawn((
        Creature { power: 3, toughness: 3 },
        Attacking { defending: player_entity },
        FirstStrike,
    )).id();
    
    // Create blocker without first strike
    let blocker = app.world.spawn((
        Creature { power: 2, toughness: 2 },
        Blocking { blocked_attackers: vec![attacker] },
        Health { current: 2, maximum: 2 },
    )).id();
    
    // Process first strike damage
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::FirstStrike);
    app.update();
    
    // Verify blocker received damage and was destroyed
    let health = app.world.get::<Health>(blocker).unwrap();
    assert_eq!(health.current, 0); // Received 3 damage from first strike attacker
    
    // Verify no damage was dealt to attacker yet (since blocker doesn't have first strike)
    let attacker_health = app.world.get::<Health>(attacker).unwrap();
    assert_eq!(attacker_health.current, attacker_health.maximum);
}

#[test]
fn test_double_strike_damage() {
    // Test that double strike creatures deal damage in both steps
    // ...
}

#[test]
fn test_first_strike_detection() {
    // Test that the system correctly detects when a first strike step is needed
    // ...
}
}

Integration Tests

#![allow(unused)]
fn main() {
#[test]
fn test_first_strike_vs_regular_damage() {
    // Test complete sequence with both first strike and regular damage
    // ...
}

#[test]
fn test_gaining_first_strike_mid_combat() {
    // Test gaining first strike during combat
    // ...
}

#[test]
fn test_losing_first_strike_mid_combat() {
    // Test losing first strike during combat
    // ...
}
}

Edge Case Tests

#![allow(unused)]
fn main() {
#[test]
fn test_first_strike_with_triggered_abilities() {
    // Test interaction between first strike damage and triggered abilities
    // ...
}

#[test]
fn test_first_strike_with_damage_prevention() {
    // Test first strike damage with damage prevention effects
    // ...
}

#[test]
fn test_first_strike_with_damage_redirection() {
    // Test first strike damage with redirection effects
    // ...
}
}

Performance Considerations

1. Conditional Step Creation: Only create the First Strike Damage step when needed.

2. Efficient Entity Filtering: Optimize filtering of entities with first strike/double strike.

3. Damage Assignment Optimization: Reuse damage assignment logic between first strike and regular damage steps.

4. State Tracking: Efficiently track state between first strike and regular damage steps.

Conclusion

The First Strike Damage step is a specialized combat sub-step that adds strategic depth to the combat system. By correctly implementing first strike and double strike mechanics, we ensure that these powerful combat abilities function as expected according to the Magic: The Gathering rules. The implementation must handle all edge cases, including mid-combat changes to first strike status, while maintaining good performance and seamless integration with the rest of the combat system.

Combat Damage

Overview

The Combat Damage step is the critical phase of combat where damage is assigned and dealt between attacking and blocking creatures, as well as to players and planeswalkers. In Commander, this step has additional significance due to the presence of Commander damage tracking and the multiplayer nature of the format.

This document outlines the implementation details, edge cases, and testing strategies for the Combat Damage step in our Commander engine.

Core Concepts

Combat Damage Flow

The Combat Damage step follows this general flow:

1. First, the active player assigns combat damage from their attacking creatures
2. Then, each defending player assigns combat damage from their blocking creatures
3. All damage is dealt simultaneously
4. State-based actions are checked, including:
   • Creatures with lethal damage are destroyed
   • Players with 0 or less life lose the game
   • Players with 21+ commander damage from a single commander lose the game
5. Combat damage triggers are placed on the stack
6. Priority passes to players in turn order

First Strike and Double Strike

Combat damage may occur in two sub-steps when creatures with first strike or double strike are involved:

1. First Strike Combat Damage - Damage from creatures with first strike or double strike
2. Regular Combat Damage - Damage from all other creatures and second instance of damage from double strike creatures

Implementation Design

Data Structures

#![allow(unused)]
fn main() {
// Represents the damage assignment for a specific attacker or blocker
struct DamageAssignment {
    source: Entity,         // The entity dealing damage
    target: Entity,         // The entity receiving damage
    amount: u32,            // Amount of damage
    is_commander_damage: bool, // Whether this is commander damage
    is_combat_damage: bool, // Always true for combat damage step
}

// Component for tracking assigned damage
#[derive(Component)]
struct AssignedDamage {
    assignments: Vec<DamageAssignment>,
}

// System resource for managing the combat damage step
struct CombatDamageSystem {
    first_strike_round_completed: bool,
    damage_assignments: HashMap<Entity, Vec<DamageAssignment>>,
}
}

Combat Damage System

#![allow(unused)]
fn main() {
fn combat_damage_system(
    mut commands: Commands,
    mut combat_system: ResMut<CombatSystem>,
    turn_manager: Res<TurnManager>,
    creature_query: Query<(Entity, &Creature, &Health, Option<&FirstStrike>, Option<&DoubleStrike>)>,
    attacker_query: Query<(Entity, &Attacking)>,
    blocker_query: Query<(Entity, &Blocking)>,
    player_query: Query<(Entity, &Player, &Health)>,
    mut commander_damage: Query<&mut CommanderDamage>,
    // Other system parameters
) {
    // Check if we need to process first strike damage
    let current_step = match turn_manager.current_phase {
        Phase::Combat(CombatStep::FirstStrike) => CombatStep::FirstStrike,
        Phase::Combat(CombatStep::CombatDamage) => CombatStep::CombatDamage,
        _ => return, // Not in a combat damage step
    };
    
    // Determine which creatures deal damage in this step
    let (first_strike_creatures, regular_creatures) = creature_query
        .iter()
        .partition(|(_, _, _, first_strike, double_strike)| 
            first_strike.is_some() || double_strike.is_some()
        );
        
    // Process creatures that deal damage in this step
    let applicable_creatures = match current_step {
        CombatStep::FirstStrike => &first_strike_creatures,
        CombatStep::CombatDamage => {
            // In regular combat damage, double strike creatures deal damage again,
            // and creatures without first/double strike deal damage for the first time
            let mut creatures = Vec::new();
            creatures.extend(regular_creatures);
            creatures.extend(
                first_strike_creatures
                    .iter()
                    .filter(|(_, _, _, _, double_strike)| double_strike.is_some())
            );
            &creatures
        }
        _ => return,
    };
    
    // Assign and deal damage
    for (entity, creature, health, _, _) in applicable_creatures {
        // Determine damage amount and recipients
        let power = creature.power;
        
        if let Ok((_, attacking)) = attacker_query.get(*entity) {
            // Attacking creature deals damage
            assign_attacker_damage(
                *entity, 
                power, 
                attacking.defending, 
                &blocker_query, 
                &mut combat_system
            );
        } else if let Ok((_, blocking)) = blocker_query.get(*entity) {
            // Blocking creature deals damage
            assign_blocker_damage(
                *entity, 
                power, 
                &blocking.blocked_attackers, 
                &mut combat_system
            );
        }
    }
    
    // Deal all assigned damage simultaneously
    process_damage_assignments(&mut commands, &combat_system, &mut commander_damage);
    
    // Check for state-based actions
    check_state_based_actions(&mut commands, &player_query, &creature_query);
    
    // If this was the first strike step, we'll continue to regular damage
    // If this was regular combat damage, we'll proceed to end of combat
    if current_step == CombatStep::FirstStrike {
        combat_system.first_strike_round_completed = true;
    } else {
        combat_system.first_strike_round_completed = false;
        // Clean up damage assignments
        combat_system.damage_assignments.clear();
    }
}
}

Damage Assignment Functions

#![allow(unused)]
fn main() {
fn assign_attacker_damage(
    attacker: Entity,
    power: u32,
    defending: Entity,
    blocker_query: &Query<(Entity, &Blocking)>,
    combat_system: &mut ResMut<CombatSystem>
) {
    // Find blockers for this attacker
    let blockers = blocker_query
        .iter()
        .filter(|(_, blocking)| blocking.blocked_attackers.contains(&attacker))
        .map(|(entity, _)| entity)
        .collect::<Vec<_>>();
    
    if blockers.is_empty() {
        // Unblocked attacker - deal damage to player or planeswalker
        combat_system.damage_assignments.entry(attacker).or_default().push(
            DamageAssignment {
                source: attacker,
                target: defending,
                amount: power,
                is_commander_damage: true, // Check if attacker is a commander
                is_combat_damage: true,
            }
        );
    } else {
        // Attacker is blocked - distribute damage among blockers
        // (In a real implementation, this would handle player choices for damage assignment)
        
        // Simplified version: divide damage evenly
        let damage_per_blocker = power / blockers.len() as u32;
        let remainder = power % blockers.len() as u32;
        
        for (i, blocker) in blockers.iter().enumerate() {
            let damage = damage_per_blocker + if i < remainder as usize { 1 } else { 0 };
            
            combat_system.damage_assignments.entry(attacker).or_default().push(
                DamageAssignment {
                    source: attacker,
                    target: *blocker,
                    amount: damage,
                    is_commander_damage: false, // Commander damage only applies to players
                    is_combat_damage: true,
                }
            );
        }
    }
}

fn assign_blocker_damage(
    blocker: Entity,
    power: u32,
    blocked_attackers: &[Entity],
    combat_system: &mut ResMut<CombatSystem>
) {
    // Simplified version: divide damage evenly among attackers
    // (In a real implementation, this would handle player choices for damage assignment)
    
    let damage_per_attacker = power / blocked_attackers.len() as u32;
    let remainder = power % blocked_attackers.len() as u32;
    
    for (i, attacker) in blocked_attackers.iter().enumerate() {
        let damage = damage_per_attacker + if i < remainder as usize { 1 } else { 0 };
        
        combat_system.damage_assignments.entry(blocker).or_default().push(
            DamageAssignment {
                source: blocker,
                target: *attacker,
                amount: damage,
                is_commander_damage: false,
                is_combat_damage: true,
            }
        );
    }
}

fn process_damage_assignments(
    commands: &mut Commands,
    combat_system: &CombatSystem,
    commander_damage: &mut Query<&mut CommanderDamage>
) {
    // Process all damage assignments
    for (source, assignments) in &combat_system.damage_assignments {
        for assignment in assignments {
            // Deal damage to target
            commands.entity(assignment.target).insert(
                DamageReceived {
                    amount: assignment.amount,
                    source: assignment.source,
                    is_combat_damage: true,
                }
            );
            
            // If this is commander damage, update commander damage tracker
            if assignment.is_commander_damage {
                if let Ok(mut cmd_damage) = commander_damage.get_mut(assignment.target) {
                    cmd_damage.add_damage(assignment.source, assignment.amount);
                }
            }
            
            // Add damage event for triggers
            commands.spawn(DamageEvent {
                source: assignment.source,
                target: assignment.target,
                amount: assignment.amount,
                is_combat_damage: true,
            });
        }
    }
}
}

Special Cases and Edge Scenarios

Trample

When an attacking creature with trample is blocked, excess damage is dealt to the defending player:

#![allow(unused)]
fn main() {
fn assign_attacker_damage_with_trample(
    attacker: Entity,
    power: u32,
    defending: Entity,
    blocker_query: &Query<(Entity, &Blocking, &Health)>,
    trample_query: &Query<&Trample>,
    combat_system: &mut ResMut<CombatSystem>
) {
    // Find blockers for this attacker
    let blockers = blocker_query
        .iter()
        .filter(|(_, blocking, _)| blocking.blocked_attackers.contains(&attacker))
        .collect::<Vec<_>>();
    
    if blockers.is_empty() {
        // Handle unblocked attacker as normal
        // ...
    } else if trample_query.get(attacker).is_ok() {
        // Attacker has trample - assign lethal damage to each blocker
        let mut remaining_damage = power;
        
        for (blocker, _, health) in &blockers {
            let lethal_damage = health.current.min(remaining_damage);
            remaining_damage -= lethal_damage;
            
            // Assign lethal damage to blocker
            combat_system.damage_assignments.entry(attacker).or_default().push(
                DamageAssignment {
                    source: attacker,
                    target: *blocker,
                    amount: lethal_damage,
                    is_commander_damage: false,
                    is_combat_damage: true,
                }
            );
        }
        
        // Assign remaining damage to player
        if remaining_damage > 0 {
            combat_system.damage_assignments.entry(attacker).or_default().push(
                DamageAssignment {
                    source: attacker,
                    target: defending,
                    amount: remaining_damage,
                    is_commander_damage: true, // Check if attacker is a commander
                    is_combat_damage: true,
                }
            );
        }
    } else {
        // Handle normal blocked creature (no trample)
        // ...
    }
}
}

Deathtouch

Creatures with deathtouch need to assign only 1 damage to be considered lethal:

#![allow(unused)]
fn main() {
fn is_lethal_damage(
    amount: u32,
    source: Entity,
    deathtouch_query: &Query<&Deathtouch>
) -> bool {
    if amount > 0 && deathtouch_query.get(source).is_ok() {
        return true;
    }
    amount > 0
}
}

Damage Prevention and Replacement

Damage can be prevented or modified by various effects:

#![allow(unused)]
fn main() {
fn apply_damage_prevention_effects(
    assignment: &mut DamageAssignment,
    prevention_query: &Query<&PreventDamage>
) {
    if let Ok(prevent) = prevention_query.get(assignment.target) {
        let prevented = prevent.amount.min(assignment.amount);
        assignment.amount -= prevented;
    }
}
}

Damage Redirection

Some effects can redirect damage to different entities:

#![allow(unused)]
fn main() {
fn apply_damage_redirection(
    assignment: &mut DamageAssignment,
    redirection_query: &Query<&RedirectDamage>
) {
    if let Ok(redirect) = redirection_query.get(assignment.target) {
        // Change the target of the damage
        assignment.target = redirect.new_target;
        // Adjust commander damage flag if needed
        assignment.is_commander_damage = is_commander_entity(redirect.new_target);
    }
}
}

Testing Strategy

Unit Tests

#![allow(unused)]
fn main() {
#[test]
fn test_basic_combat_damage() {
    // Set up test world
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, combat_damage_system);
       
    // Create attacker and defender
    let attacker = app.world.spawn((
        Creature { power: 3, toughness: 3, },
        Attacking { defending: player_entity },
    )).id();
    
    let defender = app.world.spawn((
        Player {},
        Health { current: 20, maximum: 20 },
        CommanderDamage::default(),
    )).id();
    
    // Process combat damage
    app.update();
    
    // Verify damage was dealt
    let health = app.world.get::<Health>(defender).unwrap();
    assert_eq!(health.current, 17);
}

#[test]
fn test_first_strike_damage() {
    // Set up test world with first strike creatures
    // ...
}

#[test]
fn test_blocked_creature_damage() {
    // Test damage assignment with blockers
    // ...
}

#[test]
fn test_commander_damage_tracking() {
    // Test commander damage accumulation
    // ...
}
}

Integration Tests

#![allow(unused)]
fn main() {
#[test]
fn test_full_combat_sequence() {
    // Set up a complete combat sequence with attackers, blockers,
    // and damage calculation
    // ...
}

#[test]
fn test_combat_with_damage_prevention() {
    // Test combat with damage prevention effects
    // ...
}

#[test]
fn test_combat_with_replacement_effects() {
    // Test combat with damage replacement effects
    // ...
}
}

Edge Case Tests

#![allow(unused)]
fn main() {
#[test]
fn test_damage_to_indestructible() {
    // Test damage to indestructible creatures
    // ...
}

#[test]
fn test_damage_with_deathtouch_and_trample() {
    // Test the interaction of deathtouch and trample
    // ...
}

#[test]
fn test_damage_redirection() {
    // Test redirection of combat damage
    // ...
}
}

Performance Considerations

1. Batch Damage Processing: Process all damage assignments simultaneously for better performance.

2. Damage Event Optimization: Use a more efficient event system for damage events to avoid spawning entities.

3. Damage Assignment Caching: Cache damage assignments to avoid recalculating them.

4. Parallel Processing: Use parallel processing for damage assignment when appropriate.

Conclusion

The Combat Damage step is a complex but crucial part of the Commander game engine. Proper implementation ensures fair and accurate damage calculation, especially for tracking commander damage which is a key victory condition in the format. By handling special abilities like first strike, double strike, trample, and deathtouch correctly, we create a robust combat system that faithfully represents the Magic: The Gathering rules while maintaining good performance.

End of Combat

Overview

The End of Combat step is the final phase of the combat sequence where "at end of combat" triggered abilities are put on the stack and resolved. This step also includes important cleanup activities that return the game state to normal after combat concludes. In Commander, this step is particularly important for handling multiplayer-specific combat interactions and resetting the combat state.

This document outlines the implementation details, edge cases, and testing strategies for the End of Combat step in our Commander engine.

Core Concepts

End of Combat Flow

The End of Combat step follows this general sequence:

1. "At end of combat" triggered abilities are put on the stack
2. Priority is passed to players in turn order
3. Once all players pass priority and the stack is empty, combat cleanup occurs:
   • "Until end of combat" effects end
   • Combat-specific statuses are removed
   • The game advances to the Postcombat Main Phase

Combat Cleanup

After the End of Combat step is complete, several important cleanup tasks must occur:

1. Remove all attacking and blocking statuses from creatures
2. End "until end of combat" effects
3. Clear combat damage tracking from the current turn
4. Reset any combat-specific flags or state

Implementation Design

Data Structures

#![allow(unused)]
fn main() {
// Component for tracking "until end of combat" effects
#[derive(Component)]
struct UntilEndOfCombat {
    // Any data needed for the effect
}

// System resource for managing the end of combat step
struct EndOfCombatSystem {
    triggers_processed: bool,
}
}

End of Combat System

#![allow(unused)]
fn main() {
fn end_of_combat_system(
    mut commands: Commands,
    mut combat_system: ResMut<CombatSystem>,
    turn_manager: Res<TurnManager>,
    attacker_query: Query<Entity, With<Attacking>>,
    blocker_query: Query<Entity, With<Blocking>>,
    end_of_combat_effects: Query<Entity, With<UntilEndOfCombat>>,
    end_of_combat_triggers: Query<(Entity, &EndOfCombatTrigger)>,
    // Other system parameters
) {
    // Only run during end of combat step
    if !matches!(turn_manager.current_phase, Phase::Combat(CombatStep::End)) {
        return;
    }
    
    // Process "at end of combat" triggers if not already processed
    if !combat_system.end_of_combat.triggers_processed {
        for (entity, trigger) in end_of_combat_triggers.iter() {
            // Create trigger event
            commands.spawn(TriggerEvent {
                source: entity,
                trigger_type: TriggerType::EndOfCombat,
            });
        }
        
        combat_system.end_of_combat.triggers_processed = true;
        return; // Exit to allow triggers to be processed
    }
    
    // If we've processed triggers and the stack is empty, perform combat cleanup
    if combat_system.end_of_combat.triggers_processed && turn_manager.stack_is_empty() {
        // Remove attacking status from all attackers
        for entity in attacker_query.iter() {
            commands.entity(entity).remove::<Attacking>();
        }
        
        // Remove blocking status from all blockers
        for entity in blocker_query.iter() {
            commands.entity(entity).remove::<Blocking>();
        }
        
        // End "until end of combat" effects
        for entity in end_of_combat_effects.iter() {
            commands.entity(entity).remove::<UntilEndOfCombat>();
        }
        
        // Reset combat system state
        combat_system.reset();
        
        // Combat complete, ready to advance to postcombat main phase
    }
}
}

Combat System Reset

#![allow(unused)]
fn main() {
impl CombatSystem {
    pub fn reset(&mut self) {
        self.attackers.clear();
        self.blockers.clear();
        self.damage_assignments.clear();
        self.first_strike_round_completed = false;
        self.begin_combat.triggers_processed = false;
        self.declare_attackers.triggers_processed = false;
        self.declare_blockers.triggers_processed = false;
        self.end_of_combat.triggers_processed = false;
    }
}
}

Special Cases and Edge Scenarios

Delayed End of Combat Triggers

Some effects create delayed triggered abilities that trigger at the end of combat:

#![allow(unused)]
fn main() {
fn create_delayed_end_of_combat_trigger(
    commands: &mut Commands,
    source: Entity,
    effect: impl Fn(&mut Commands) + Send + Sync + 'static
) {
    commands.spawn((
        DelayedTrigger {
            source,
            trigger_type: TriggerType::EndOfCombat,
            effect: Box::new(effect),
        },
    ));
}
}

Regeneration Shield Cleanup

Regeneration shields that were used during combat should be removed:

#![allow(unused)]
fn main() {
fn cleanup_regeneration_shields(
    mut commands: Commands,
    regeneration_query: Query<(Entity, &RegenerationShield)>
) {
    for (entity, shield) in regeneration_query.iter() {
        if shield.used {
            commands.entity(entity).remove::<RegenerationShield>();
        }
    }
}
}

"Until End of Combat" Effects

Effects that last until end of combat need special handling:

#![allow(unused)]
fn main() {
fn apply_until_end_of_combat_effect(
    commands: &mut Commands,
    target: Entity,
    effect_data: EffectData
) {
    // Apply the effect
    commands.entity(target).insert(effect_data.component);
    
    // Mark it to be removed at end of combat
    commands.entity(target).insert(UntilEndOfCombat {
        // Any necessary data
    });
}
}

Phasing During End of Combat

Creatures that phase out during combat might need special handling during end of combat:

#![allow(unused)]
fn main() {
fn handle_phased_combat_participants(
    mut commands: Commands,
    phased_attackers: Query<Entity, (With<Attacking>, With<PhasedOut>)>,
    phased_blockers: Query<Entity, (With<Blocking>, With<PhasedOut>)>
) {
    // Remove combat status from phased creatures too
    for entity in phased_attackers.iter() {
        commands.entity(entity).remove::<Attacking>();
    }
    
    for entity in phased_blockers.iter() {
        commands.entity(entity).remove::<Blocking>();
    }
}
}

Testing Strategy

Unit Tests

#![allow(unused)]
fn main() {
#[test]
fn test_basic_end_of_combat_cleanup() {
    // Set up test world
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, end_of_combat_system);
       
    // Create attackers and blockers
    let attacker = app.world.spawn((
        Creature { power: 3, toughness: 3 },
        Attacking { defending: player_entity },
    )).id();
    
    let blocker = app.world.spawn((
        Creature { power: 2, toughness: 2 },
        Blocking { blocked_attackers: vec![attacker] },
    )).id();
    
    // Simulate end of combat step
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::End);
    app.world.resource_mut::<CombatSystem>().end_of_combat.triggers_processed = true;
    
    // Process end of combat
    app.update();
    
    // Verify cleanup
    assert!(!app.world.entity(attacker).contains::<Attacking>());
    assert!(!app.world.entity(blocker).contains::<Blocking>());
}

#[test]
fn test_end_of_combat_triggers() {
    // Test triggers that happen at end of combat
    // ...
}

#[test]
fn test_until_end_of_combat_effects() {
    // Test that effects with "until end of combat" duration are removed
    // ...
}
}

Integration Tests

#![allow(unused)]
fn main() {
#[test]
fn test_full_combat_sequence_with_end_phase() {
    // Test a complete combat sequence from beginning to end
    // ...
}

#[test]
fn test_end_of_combat_with_replacement_effects() {
    // Test end of combat with replacement effects that modify cleanup
    // ...
}
}

Edge Case Tests

#![allow(unused)]
fn main() {
#[test]
fn test_end_of_combat_with_phased_creatures() {
    // Test end of combat with phased creatures
    // ...
}

#[test]
fn test_end_of_combat_when_player_loses() {
    // Test what happens if a player loses during end of combat
    // ...
}

#[test]
fn test_end_of_combat_with_delayed_triggers() {
    // Test delayed triggers that happen at end of combat
    // ...
}
}

Performance Considerations

1. Batch Removal Operations: Group similar removal operations together for better performance.

2. Minimize Query Iterations: Structure queries to minimize iterations over entities.

3. State Reset Optimization: Efficiently reset the combat state without unnecessary operations.

4. Effect Tracking: Use an efficient system for tracking and removing "until end of combat" effects.

Conclusion

The End of Combat step is a critical transition point in the Commander game flow. Proper implementation ensures that combat-related statuses and effects are appropriately cleaned up, and the game state is correctly prepared for the next phase. By handling all "at end of combat" triggers and cleanup operations correctly, we create a robust and reliable combat system that maintains game state integrity while supporting all the complex interactions present in the Commander format.

Combat Abilities

Overview

Magic: The Gathering includes numerous abilities that specifically interact with combat. In Commander, these abilities gain additional complexity due to the multiplayer nature of the format and the special rules surrounding commander damage. This document details how combat-specific abilities are implemented and tested in our game engine.

Combat Keywords

Combat keywords are implemented through a combination of component flags and systems that check for these keywords during the appropriate combat steps.

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Keyword {
    // Combat-specific keywords
    FirstStrike,
    DoubleStrike,
    Deathtouch,
    Trample,
    Vigilance,
    Menace,
    Flying,
    Reach,
    Indestructible,
    Lifelink,
    // Other keywords...
}

// Component that stores a creature's abilities
#[derive(Component, Clone)]
pub struct Abilities(pub Vec<Ability>);

// Different ability types
#[derive(Debug, Clone)]
pub enum Ability {
    Keyword(Keyword),
    Triggered(Trigger, Effect),
    Activated(ActivationCost, Effect),
    Static(StaticEffect),
    // Other ability types...
}

// Implement utility functions for checking abilities
impl Creature {
    pub fn has_ability(&self, ability: Ability) -> bool {
        // Implementation details omitted for brevity
        false
    }
    
    pub fn has_keyword(&self, keyword: Keyword) -> bool {
        // Check if the creature has the specified keyword
        if let Ok(abilities) = abilities_query.get(self.entity) {
            abilities.0.iter().any(|ability| {
                if let Ability::Keyword(kw) = ability {
                    *kw == keyword
                } else {
                    false
                }
            })
        } else {
            false
        }
    }
}
}

Keyword Implementation Systems

Each combat keyword has a dedicated system that implements its effect:

First Strike and Double Strike

#![allow(unused)]
fn main() {
pub fn first_strike_damage_system(
    mut combat_system: ResMut<CombatSystem>,
    turn_manager: Res<TurnManager>,
    creature_query: Query<(Entity, &Creature)>,
    mut game_events: EventWriter<GameEvent>,
) {
    // Only run during the first strike damage step
    if turn_manager.current_phase != Phase::Combat(CombatStep::FirstStrike) {
        return;
    }
    
    // Get all attackers with first strike or double strike
    let first_strike_attackers = combat_system.attackers
        .iter()
        .filter_map(|(attacker, attack_data)| {
            if let Ok((entity, creature)) = creature_query.get(*attacker) {
                if creature.has_keyword(Keyword::FirstStrike) || 
                   creature.has_keyword(Keyword::DoubleStrike) {
                    return Some((attacker, attack_data));
                }
            }
            None
        })
        .collect::<Vec<_>>();
    
    // Get all blockers with first strike or double strike
    let first_strike_blockers = combat_system.blockers
        .iter()
        .filter_map(|(blocker, block_data)| {
            if let Ok((entity, creature)) = creature_query.get(*blocker) {
                if creature.has_keyword(Keyword::FirstStrike) || 
                   creature.has_keyword(Keyword::DoubleStrike) {
                    return Some((blocker, block_data));
                }
            }
            None
        })
        .collect::<Vec<_>>();
    
    // Process first strike combat damage
    // Implementation details omitted for brevity
    
    // Emit event for first strike damage
    game_events.send(GameEvent::FirstStrikeDamageDealt {
        attackers: first_strike_attackers.len(),
        blockers: first_strike_blockers.len(),
    });
}
}

Deathtouch

#![allow(unused)]
fn main() {
pub fn apply_deathtouch_system(
    combat_system: Res<CombatSystem>,
    creature_query: Query<(Entity, &Creature)>,
    mut commands: Commands,
) {
    // Find all creatures with deathtouch that dealt damage
    let deathtouch_creatures = combat_system.combat_history
        .iter()
        .filter_map(|event| {
            if let CombatEvent::DamageDealt { source, target, amount, .. } = event {
                if *amount > 0 {
                    if let Ok((entity, creature)) = creature_query.get(*source) {
                        if creature.has_keyword(Keyword::Deathtouch) {
                            return Some((source, target));
                        }
                    }
                }
            }
            None
        })
        .collect::<Vec<_>>();
    
    // Apply destroy effect to creatures that were damaged by deathtouch
    for (source, target) in deathtouch_creatures {
        // Only apply to creatures, not players or planeswalkers
        if creature_query.contains(*target) {
            // Mark creature as destroyed
            commands.entity(*target).insert(Destroyed {
                source: *source,
                reason: DestructionReason::Deathtouch,
            });
        }
    }
}
}

Trample

#![allow(unused)]
fn main() {
pub fn apply_trample_damage_system(
    mut combat_system: ResMut<CombatSystem>,
    creature_query: Query<(Entity, &Creature)>,
    blocker_toughness_query: Query<&Creature>,
    player_query: Query<(Entity, &mut Player)>,
    mut game_events: EventWriter<GameEvent>,
) {
    // Find all creatures with trample that are being blocked
    for (attacker, attack_data) in combat_system.attackers.iter() {
        // Only process if the attacker has trample
        if let Ok((entity, creature)) = creature_query.get(*attacker) {
            if !creature.has_keyword(Keyword::Trample) {
                continue;
            }
            
            // Check if this attacker is blocked
            let blockers: Vec<Entity> = combat_system.blockers.iter()
                .filter_map(|(blocker, block_data)| {
                    if block_data.blocked_attackers.contains(attacker) {
                        Some(*blocker)
                    } else {
                        None
                    }
                })
                .collect();
            
            // Only apply trample if the creature is blocked
            if !blockers.is_empty() {
                // Calculate total blocker toughness
                let total_blocker_toughness: u32 = blockers.iter()
                    .filter_map(|blocker| {
                        blocker_toughness_query.get(*blocker).ok().map(|creature| creature.toughness)
                    })
                    .sum();
                
                // Calculate trample damage (attacker power - total blocker toughness)
                let trample_damage = creature.power.saturating_sub(total_blocker_toughness);
                
                // Apply trample damage to defending player if there's excess damage
                if trample_damage > 0 {
                    // Only apply to players, not planeswalkers
                    for (player_entity, mut player) in player_query.iter_mut() {
                        if player_entity == attack_data.defender {
                            // Apply the damage
                            player.life_total -= trample_damage as i32;
                            
                            // Record the damage event
                            combat_system.combat_history.push_back(CombatEvent::DamageDealt {
                                source: *attacker,
                                target: player_entity,
                                amount: trample_damage,
                                is_commander_damage: attack_data.is_commander,
                            });
                            
                            // Check if player lost from trample damage
                            if player.life_total <= 0 {
                                game_events.send(GameEvent::PlayerLost {
                                    player: player_entity,
                                    reason: LossReason::ZeroLife,
                                });
                            }
                            
                            break;
                        }
                    }
                }
            }
        }
    }
}
}

Flying and Reach

#![allow(unused)]
fn main() {
pub fn validate_blocks_flying_system(
    mut combat_system: ResMut<CombatSystem>,
    creature_query: Query<(Entity, &Creature)>,
    mut block_events: EventWriter<BlockValidationEvent>,
) {
    // Check for illegal blocks involving flying creatures
    let mut illegal_blocks = Vec::new();
    
    for (blocker, block_data) in combat_system.blockers.iter() {
        // Get blocker details
        if let Ok((blocker_entity, blocker_creature)) = creature_query.get(*blocker) {
            // Check if blocker has reach or flying
            let can_block_flying = blocker_creature.has_keyword(Keyword::Flying) || 
                                  blocker_creature.has_keyword(Keyword::Reach);
            
            // Check all attackers this creature is blocking
            for attacker in &block_data.blocked_attackers {
                if let Ok((attacker_entity, attacker_creature)) = creature_query.get(*attacker) {
                    // If attacker has flying and blocker can't block flying, this is illegal
                    if attacker_creature.has_keyword(Keyword::Flying) && !can_block_flying {
                        illegal_blocks.push((*blocker, *attacker));
                    }
                }
            }
        }
    }
    
    // Remove illegal blocks
    for (blocker, attacker) in illegal_blocks {
        // Remove the block relationship
        if let Some(mut block_data) = combat_system.blockers.get_mut(&blocker) {
            block_data.blocked_attackers.retain(|a| *a != attacker);
            
            // If no more attackers, remove blocker entry
            if block_data.blocked_attackers.is_empty() {
                combat_system.blockers.remove(&blocker);
            }
        }
        
        // Emit event for illegal block
        block_events.send(BlockValidationEvent::IllegalBlock {
            blocker,
            attacker,
            reason: "Can't block flying".to_string(),
        });
    }
}
}

Menace

#![allow(unused)]
fn main() {
pub fn validate_blocks_menace_system(
    mut combat_system: ResMut<CombatSystem>,
    creature_query: Query<(Entity, &Creature)>,
    mut block_events: EventWriter<BlockValidationEvent>,
) {
    // Find attackers with menace that are being blocked by only one creature
    let menace_violations = combat_system.attackers
        .iter()
        .filter_map(|(attacker, attack_data)| {
            // Check if attacker has menace
            if let Ok((entity, creature)) = creature_query.get(*attacker) {
                if creature.has_keyword(Keyword::Menace) {
                    // Count blockers for this attacker
                    let blocker_count = combat_system.blockers
                        .values()
                        .filter(|block_data| block_data.blocked_attackers.contains(attacker))
                        .count();
                    
                    // Menace requires at least 2 blockers
                    if blocker_count == 1 {
                        // Find the single blocker
                        let blocker = combat_system.blockers
                            .iter()
                            .find_map(|(blocker, block_data)| {
                                if block_data.blocked_attackers.contains(attacker) {
                                    Some(*blocker)
                                } else {
                                    None
                                }
                            })
                            .unwrap();
                        
                        return Some((*attacker, blocker));
                    }
                }
            }
            None
        })
        .collect::<Vec<_>>();
    
    // Remove blocks that violate menace
    for (attacker, blocker) in menace_violations {
        // Remove the block relationship
        if let Some(mut block_data) = combat_system.blockers.get_mut(&blocker) {
            block_data.blocked_attackers.retain(|a| *a != attacker);
            
            // If no more attackers, remove blocker entry
            if block_data.blocked_attackers.is_empty() {
                combat_system.blockers.remove(&blocker);
            }
        }
        
        // Emit event for illegal block
        block_events.send(BlockValidationEvent::IllegalBlock {
            blocker,
            attacker,
            reason: "Menace requires at least two blockers".to_string(),
        });
    }
}
}

Vigilance

#![allow(unused)]
fn main() {
pub fn apply_vigilance_system(
    combat_system: Res<CombatSystem>,
    creature_query: Query<(Entity, &Creature)>,
    mut commands: Commands,
) {
    // Find attackers with vigilance and ensure they don't get tapped
    for (attacker, _) in combat_system.attackers.iter() {
        if let Ok((entity, creature)) = creature_query.get(*attacker) {
            if creature.has_keyword(Keyword::Vigilance) {
                // Remove the Tapped component if it exists
                commands.entity(*attacker).remove::<Tapped>();
            }
        }
    }
}
}

Triggered Combat Abilities

Triggered abilities are a major part of combat in Magic. These are implemented using a trigger system:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone)]
pub enum Trigger {
    // Combat-related triggers
    WhenAttacks { conditions: Vec<TriggerCondition> },
    WhenBlocks { conditions: Vec<TriggerCondition> },
    WhenBlocked { conditions: Vec<TriggerCondition> },
    WhenDealsCombat { conditions: Vec<TriggerCondition> },
    WheneverCreatureAttacks { conditions: Vec<TriggerCondition> },
    WheneverCreatureBlocks { conditions: Vec<TriggerCondition> },
    BeginningOfCombat { controller_condition: ControllerCondition },
    EndOfCombat { controller_condition: ControllerCondition },
    // Other triggers...
}

pub fn combat_trigger_system(
    combat_system: Res<CombatSystem>,
    turn_manager: Res<TurnManager>,
    mut stack: ResMut<Stack>,
    entity_query: Query<(Entity, &Card, &Abilities)>,
) {
    // Only run during the appropriate combat step
    if !matches!(turn_manager.current_phase, 
        Phase::Combat(CombatStep::DeclareAttackers) | 
        Phase::Combat(CombatStep::DeclareBlockers) | 
        Phase::Combat(CombatStep::CombatDamage)) {
        return;
    }
    
    // Collect triggered abilities based on the current combat step
    let mut triggered_abilities = Vec::new();
    
    // Check all entities with abilities
    for (entity, card, abilities) in entity_query.iter() {
        for ability in &abilities.0 {
            if let Ability::Triggered(trigger, effect) = ability {
                match trigger {
                    // Check if we're in declare attackers and this is a "when attacks" trigger
                    Trigger::WhenAttacks { conditions } 
                        if turn_manager.current_phase == Phase::Combat(CombatStep::DeclareAttackers) => {
                        // Check if this entity is attacking
                        if let Some(attack_data) = combat_system.attackers.get(&entity) {
                            // Check if conditions are met
                            if all_conditions_met(conditions, entity, attack_data.defender) {
                                triggered_abilities.push((entity, effect.clone(), get_controller(entity)));
                            }
                        }
                    },
                    
                    // Similar checks for other triggers...
                    _ => {}
                }
            }
        }
    }
    
    // Add triggered abilities to the stack in APNAP order
    let active_player = turn_manager.get_active_player();
    let ordered_triggers = order_triggers_by_apnap(triggered_abilities, active_player);
    
    for (source, effect, controller) in ordered_triggers {
        stack.push(StackItem::Ability {
            source,
            effect,
            controller,
        });
    }
}
}

Special Combat Abilities

Ninjutsu

#![allow(unused)]
fn main() {
pub fn handle_ninjutsu_system(
    mut combat_system: ResMut<CombatSystem>,
    turn_manager: Res<TurnManager>,
    mut commands: Commands,
    card_query: Query<(Entity, &Card, &Abilities, Option<&Commander>)>,
    mut activation_events: EventReader<NinjutsuActivationEvent>,
    mut creature_query: Query<(Entity, &mut Creature)>,
) {
    // Only active during declare attackers step after attacks are declared
    if turn_manager.current_phase != Phase::Combat(CombatStep::DeclareAttackers) 
       || combat_system.attackers.is_empty() {
        return;
    }
    
    // Process ninjutsu activations
    for event in activation_events.iter() {
        if let Ok((entity, card, abilities, commander)) = card_query.get(event.ninja) {
            // Verify card has ninjutsu or commander ninjutsu
            let has_ninjutsu = abilities.0.iter().any(|ability| {
                matches!(ability, Ability::Activated(ActivationCost::Ninjutsu(_), _))
            });
            
            let has_commander_ninjutsu = commander.is_some() && abilities.0.iter().any(|ability| {
                matches!(ability, Ability::Activated(ActivationCost::CommanderNinjutsu(_), _))
            });
            
            if has_ninjutsu || has_commander_ninjutsu {
                // Verify unblocked attacker
                if !combat_system.attackers.contains_key(&event.unblocked_attacker) {
                    continue;
                }
                
                // Verify attacker is unblocked
                let is_blocked = combat_system.blockers.values().any(|block_data| {
                    block_data.blocked_attackers.contains(&event.unblocked_attacker)
                });
                
                if is_blocked {
                    continue;
                }
                
                // Get defender
                let defender = combat_system.attackers[&event.unblocked_attacker].defender;
                
                // Return unblocked attacker to hand
                // Implementation details omitted for brevity
                
                // Put ninja onto battlefield tapped and attacking
                // Implementation details omitted for brevity
                
                // Update combat system
                combat_system.attackers.remove(&event.unblocked_attacker);
                combat_system.attackers.insert(event.ninja, AttackData {
                    attacker: event.ninja,
                    defender,
                    is_commander: commander.is_some(),
                    requirements: Vec::new(),
                    restrictions: Vec::new(),
                });
            }
        }
    }
}
}

Protection

#![allow(unused)]
fn main() {
pub fn apply_protection_system(
    mut combat_system: ResMut<CombatSystem>,
    creature_query: Query<(Entity, &Creature, &ActiveEffects)>,
    mut combat_events: EventWriter<CombatEvent>,
) {
    // Check for protection effects
    let mut invalid_blocks = Vec::new();
    let mut prevented_damage = Vec::new();
    
    // Check blocks against protection
    for (blocker, block_data) in combat_system.blockers.iter() {
        if let Ok((blocker_entity, _, effects)) = creature_query.get(*blocker) {
            for attacker in &block_data.blocked_attackers {
                if has_protection_from(*blocker, *attacker, &creature_query) {
                    invalid_blocks.push((*blocker, *attacker));
                }
            }
        }
    }
    
    // Check damage against protection
    let damage_events = combat_system.combat_history
        .iter()
        .filter_map(|event| {
            if let CombatEvent::DamageDealt { source, target, amount, is_commander_damage } = event {
                Some((*source, *target, *amount, *is_commander_damage))
            } else {
                None
            }
        })
        .collect::<Vec<_>>();
    
    for (source, target, amount, is_commander_damage) in damage_events {
        if has_protection_from(target, source, &creature_query) {
            prevented_damage.push((source, target, amount, is_commander_damage));
        }
    }
    
    // Remove invalid blocks
    for (blocker, attacker) in invalid_blocks {
        if let Some(mut block_data) = combat_system.blockers.get_mut(&blocker) {
            block_data.blocked_attackers.retain(|a| *a != attacker);
        }
    }
    
    // Record damage prevention events
    for (source, target, amount, is_commander_damage) in prevented_damage {
        combat_events.send(CombatEvent::DamagePrevented {
            source,
            target,
            amount,
            reason: PreventionReason::Protection,
        });
    }
}

// Helper function to check if an entity has protection from another
fn has_protection_from(
    protected: Entity,
    source: Entity,
    creature_query: &Query<(Entity, &Creature, &ActiveEffects)>,
) -> bool {
    if let Ok((_, _, effects)) = creature_query.get(protected) {
        for effect in &effects.0 {
            match effect {
                Effect::ProtectionFromColor(color) => {
                    // Check if source has the protected color
                    if let Ok((_, source_creature, _)) = creature_query.get(source) {
                        if source_creature.colors.contains(color) {
                            return true;
                        }
                    }
                },
                Effect::ProtectionFromCreatureType(creature_type) => {
                    // Check if source has the protected creature type
                    if let Ok((_, source_creature, _)) = creature_query.get(source) {
                        if source_creature.types.contains(creature_type) {
                            return true;
                        }
                    }
                },
                Effect::ProtectionFromPlayer(player) => {
                    // Check if source is controlled by the protected player
                    // Implementation details omitted for brevity
                },
                Effect::ProtectionFromEverything => {
                    return true;
                },
                _ => {}
            }
        }
    }
    
    false
}
}

Edge Cases

Multiple Combats

Some cards create additional combat phases. These need special handling:

#![allow(unused)]
fn main() {
pub fn handle_additional_combat_phases(
    mut turn_manager: ResMut<TurnManager>,
    mut combat_system: ResMut<CombatSystem>,
    mut creature_query: Query<(Entity, &mut Creature)>,
    mut phase_events: EventReader<PhaseEvent>,
) {
    // Check for additional combat phase events
    for event in phase_events.iter() {
        if let PhaseEvent::AdditionalPhase { phase, source } = event {
            if matches!(phase, Phase::Combat(_)) {
                // Reset combat state for the new phase
                combat_system.reset();
                combat_system.is_additional_combat_phase = true;
                
                // Reset attacked/blocked flags on creatures
                for (entity, mut creature) in creature_query.iter_mut() {
                    creature.attacking = None;
                    creature.blocking.clear();
                }
                
                // Update turn manager
                turn_manager.additional_phases.push_back((*phase, *source));
            }
        }
    }
}
}

Changing Abilities During Combat

Creatures can gain or lose abilities during combat:

#![allow(unused)]
fn main() {
pub fn update_combat_abilities_system(
    mut creature_query: Query<(Entity, &mut Creature, &ActiveEffects)>,
    mut combat_system: ResMut<CombatSystem>,
    mut ability_events: EventReader<AbilityChangeEvent>,
) {
    // Process ability change events
    for event in ability_events.iter() {
        if let AbilityChangeEvent::GainedKeyword { entity, keyword } = event {
            // Update entity if it's involved in combat
            if combat_system.attackers.contains_key(entity) || 
               combat_system.blockers.contains_key(entity) {
                // Special handling for combat-relevant keywords
                match keyword {
                    Keyword::FirstStrike | Keyword::DoubleStrike => {
                        // May need to recalculate damage for first strike step
                        if combat_system.active_combat_step == Some(CombatStep::DeclareBlockers) {
                            // Flag that first strike needs to be checked
                            combat_system.first_strike_recalculation_needed = true;
                        }
                    },
                    Keyword::Flying => {
                        // May need to recalculate blocks for flying
                        if let Some(block_data) = combat_system.blockers.get(entity) {
                            // Check if this creature is now blocking a flyer illegally
                            // Implementation details omitted for brevity
                        }
                    },
                    Keyword::Vigilance => {
                        // If creature already attacked, untap it
                        if combat_system.attackers.contains_key(entity) {
                            // Implementation details omitted for brevity
                        }
                    },
                    // Handle other keywords...
                    _ => {}
                }
            }
        }
        else if let AbilityChangeEvent::LostKeyword { entity, keyword } = event {
            // Similar handling for losing keywords
            // Implementation details omitted for brevity
        }
    }
}
}

Testing Strategy

Unit Tests for Combat Abilities

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_deathtouch() {
        let mut app = App::new();
        app.add_systems(Update, apply_deathtouch_system);
        
        // Setup test entities with deathtouch
        let attacker = app.world.spawn((
            Card::default(),
            Creature { power: 1, toughness: 1, ..Default::default() },
            Abilities(vec![Ability::Keyword(Keyword::Deathtouch)]),
        )).id();
        
        let blocker = app.world.spawn((
            Card::default(),
            Creature { power: 5, toughness: 5, ..Default::default() },
        )).id();
        
        // Create combat history with damage event
        let mut combat_system = CombatSystem::default();
        combat_system.combat_history.push_back(CombatEvent::DamageDealt {
            source: attacker,
            target: blocker,
            amount: 1,
            is_commander_damage: false,
        });
        app.insert_resource(combat_system);
        
        // Run the system
        app.update();
        
        // Verify blocker was destroyed by deathtouch
        assert!(app.world.entity(blocker).contains::<Destroyed>());
    }
    
    #[test]
    fn test_trample() {
        let mut app = App::new();
        app.add_systems(Update, apply_trample_damage_system);
        
        // Setup test entities
        let player = app.world.spawn((
            Player { life_total: 40, commander_damage: HashMap::new(), ..Default::default() },
        )).id();
        
        let attacker = app.world.spawn((
            Card::default(),
            Creature { power: 5, toughness: 5, ..Default::default() },
            Abilities(vec![Ability::Keyword(Keyword::Trample)]),
        )).id();
        
        let blocker = app.world.spawn((
            Card::default(),
            Creature { power: 2, toughness: 2, ..Default::default() },
        )).id();
        
        // Create combat system with attacker and blocker
        let mut combat_system = CombatSystem::default();
        combat_system.attackers.insert(attacker, AttackData {
            attacker,
            defender: player,
            is_commander: false,
            requirements: Vec::new(),
            restrictions: Vec::new(),
        });
        
        combat_system.blockers.insert(blocker, BlockData {
            blocker,
            blocked_attackers: vec![attacker],
            requirements: Vec::new(),
            restrictions: Vec::new(),
        });
        
        app.insert_resource(combat_system);
        
        // Run the system
        app.update();
        
        // Verify trample damage was dealt to player (5 power - 2 toughness = 3 damage)
        let player_component = app.world.entity(player).get::<Player>().unwrap();
        assert_eq!(player_component.life_total, 40 - 3);
        
        // Verify combat history contains damage event
        let combat_system = app.world.resource::<CombatSystem>();
        assert!(combat_system.combat_history.iter().any(|event| {
            matches!(event, CombatEvent::DamageDealt { source, target, amount, .. } 
                if *source == attacker && *target == player && *amount == 3)
        }));
    }
    
    #[test]
    fn test_flying_and_reach() {
        let mut app = App::new();
        app.add_systems(Update, validate_blocks_flying_system);
        
        // Setup test entities
        let flying_creature = app.world.spawn((
            Card::default(),
            Creature { power: 3, toughness: 3, ..Default::default() },
            Abilities(vec![Ability::Keyword(Keyword::Flying)]),
        )).id();
        
        let normal_creature = app.world.spawn((
            Card::default(),
            Creature { power: 2, toughness: 2, ..Default::default() },
        )).id();
        
        let reach_creature = app.world.spawn((
            Card::default(),
            Creature { power: 1, toughness: 4, ..Default::default() },
            Abilities(vec![Ability::Keyword(Keyword::Reach)]),
        )).id();
        
        // Create combat system with illegal block
        let mut combat_system = CombatSystem::default();
        combat_system.attackers.insert(flying_creature, AttackData {
            attacker: flying_creature,
            defender: Entity::from_raw(999), // Dummy defender
            is_commander: false,
            requirements: Vec::new(),
            restrictions: Vec::new(),
        });
        
        combat_system.blockers.insert(normal_creature, BlockData {
            blocker: normal_creature,
            blocked_attackers: vec![flying_creature],
            requirements: Vec::new(),
            restrictions: Vec::new(),
        });
        
        combat_system.blockers.insert(reach_creature, BlockData {
            blocker: reach_creature,
            blocked_attackers: vec![flying_creature],
            requirements: Vec::new(),
            restrictions: Vec::new(),
        });
        
        app.insert_resource(combat_system);
        
        // Set up event listener
        app.add_event::<BlockValidationEvent>();
        
        // Run the system
        app.update();
        
        // Verify normal creature can't block the flyer
        let combat_system = app.world.resource::<CombatSystem>();
        assert!(!combat_system.blockers.get(&normal_creature)
            .map_or(false, |data| data.blocked_attackers.contains(&flying_creature)));
        
        // Verify reach creature can still block the flyer
        assert!(combat_system.blockers.get(&reach_creature)
            .map_or(false, |data| data.blocked_attackers.contains(&flying_creature)));
    }
    
    // Additional tests...
}
}

Integration Tests for Combat Abilities

#![allow(unused)]
fn main() {
#[cfg(test)]
mod integration_tests {
    use super::*;
    
    #[test]
    fn test_keyword_interactions() {
        let mut builder = CombatScenarioBuilder::new();
        
        // Setup a combat scenario with multiple keyword interactions
        let opponent = builder.add_player();
        
        // Flying attacker with lifelink and double strike
        let attacker = builder.add_attacker(3, 3, builder.active_player, false);
        builder.add_effect(attacker, Effect::Keyword(Keyword::Flying));
        builder.add_effect(attacker, Effect::Keyword(Keyword::Lifelink));
        builder.add_effect(attacker, Effect::Keyword(Keyword::DoubleStrike));
        
        // Normal blocker can't block flying
        let blocker1 = builder.add_blocker(2, 2, opponent);
        
        // Reach blocker can block flying
        let blocker2 = builder.add_blocker(1, 1, opponent);
        builder.add_effect(blocker2, Effect::Keyword(Keyword::Reach));
        
        // Set up attacks and blocks
        builder.declare_attacks(vec![(attacker, opponent)]);
        builder.declare_blocks(vec![(blocker2, vec![attacker])]);
        
        // Execute combat
        let result = builder.execute();
        
        // Verify: 
        // 1. First strike damage killed blocker2
        // 2. Double strike allowed second hit to player
        // 3. Lifelink gained life
        
        // Check blocker died
        let blocker2_status = result.creature_status.get(&blocker2).unwrap();
        assert!(blocker2_status.destroyed);
        
        // Check player took damage from second hit (double strike)
        assert_eq!(result.player_life[&opponent], 40 - 3);
        
        // Check controller gained life from lifelink
        let active_player_life = result.player_life[&builder.active_player];
        assert_eq!(active_player_life, 40 + 6); // 3 damage twice from double strike
    }
    
    #[test]
    fn test_triggered_abilities() {
        // Test implementation for combat-triggered abilities
        // Implementation details omitted for brevity
    }
    
    #[test]
    fn test_ninjutsu() {
        // Test implementation for ninjutsu
        // Implementation details omitted for brevity
    }
    
    // Additional integration tests...
}
}

Combos and Interactions

The combat system needs to handle complex ability interactions:

#![allow(unused)]
fn main() {
pub fn handle_ability_interactions(
    combat_system: Res<CombatSystem>,
    entity_query: Query<(Entity, &Creature, &ActiveEffects)>,
    mut destroy_events: EventWriter<DestroyEvent>,
    mut damage_events: EventWriter<DamageEvent>,
) {
    // Track relevant ability combinations
    let mut indestructible_entities = HashSet::new();
    let mut damage_redirection_map = HashMap::new();
    let mut regeneration_shields = HashMap::new();
    
    // Collect all combat-relevant abilities
    for (entity, _, effects) in entity_query.iter() {
        for effect in &effects.0 {
            match effect {
                Effect::Indestructible => {
                    indestructible_entities.insert(entity);
                },
                Effect::RedirectDamage { target } => {
                    damage_redirection_map.insert(entity, *target);
                },
                Effect::RegenerationShield => {
                    regeneration_shields.entry(entity).or_insert(0) += 1;
                },
                // Handle other effects
                _ => {}
            }
        }
    }
    
    // Process combat damage events considering special abilities
    for event in combat_system.combat_history.iter() {
        if let CombatEvent::DamageDealt { source, target, amount, is_commander_damage } = event {
            // Check for damage redirection
            let actual_target = damage_redirection_map.get(target).copied().unwrap_or(*target);
            
            // Check if damage would be lethal
            if let Ok((_, creature, _)) = entity_query.get(actual_target) {
                if creature.toughness <= creature.damage + amount {
                    // Check for indestructible
                    if indestructible_entities.contains(&actual_target) {
                        // Creature survives despite lethal damage
                        continue;
                    }
                    
                    // Check for regeneration shield
                    if let Some(shields) = regeneration_shields.get_mut(&actual_target) {
                        if *shields > 0 {
                            // Use a regeneration shield
                            *shields -= 1;
                            
                            // Emit regeneration event
                            // Implementation details omitted
                            
                            continue;
                        }
                    }
                    
                    // No protection, creature is destroyed
                    destroy_events.send(DestroyEvent {
                        entity: actual_target,
                        source: *source,
                        reason: DestructionReason::LethalDamage,
                    });
                }
            }
        }
    }
}
}

Conclusion

Combat abilities add significant complexity to the Commander format, requiring careful implementation and testing. The systems described here work together to handle the various keywords, triggers, and special cases that can arise during combat. By properly implementing and testing these abilities, we ensure that the combat system correctly follows the rules of Magic: The Gathering while providing the strategic depth that makes Commander such a popular format.

Combat Tests

This section contains tests related to the combat system in the Commander format, focusing on both the standard combat rules and Commander-specific interactions.

Subsections

Edge Cases

Tests for complex and edge case combat scenarios, including Commander-specific interactions and intricate card combinations.

Phasing

Tests related to phasing effects during combat, including their impact on attackers, blockers, and combat damage.

Pump Spells

Tests for combat interactions with pump spells and other power/toughness modifying effects that occur during combat.

Combat Edge Cases Tests

This section contains tests for complex and edge case scenarios in the combat system that are specific to the Commander format.

Tests

Commander-Specific Interactions

Tests for combat mechanics that interact with Commander-specific rules, such as:

• Commander damage tracking
• Combat abilities on Commander cards
• Commander-specific combat triggers

Complex Interactions

Tests for intricate card combinations and rules interactions during combat, including:

• Multiple blocking and damage assignment
• Replacement effects during combat
• Unusual attack and block restrictions
• Multiple combat phases
• Layer system interactions affecting combat

Commander-Specific Combat Tests

Overview

This document outlines test cases for Commander-specific combat scenarios, focusing on the unique rules and edge cases that arise in the Commander format. These tests are critical for ensuring our Commander engine correctly handles format-specific interactions during combat.

Test Case: Commander Damage Tracking

Test: Multiple Sources of Commander Damage

#![allow(unused)]
fn main() {
#[test]
fn test_multiple_commanders_damage_tracking() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (combat_damage_system, state_based_actions_system));
       
    // Create player
    let player = app.world.spawn((
        Player {},
        Health { current: 40, maximum: 40 },
        CommanderDamage::default(),
    )).id();
    
    // Create commanders from different players
    let commander1 = app.world.spawn((
        Creature { power: 5, toughness: 5 },
        Commander { owner: opponent1 },
        Attacking { defending: player },
    )).id();
    
    let commander2 = app.world.spawn((
        Creature { power: 3, toughness: 3 },
        Commander { owner: opponent2 },
        Attacking { defending: player },
    )).id();
    
    let opponent1 = app.world.spawn(Player {}).id();
    let opponent2 = app.world.spawn(Player {}).id();
    
    // Process combat damage for first attack
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::CombatDamage);
    app.update();
    
    // Verify commander damage was tracked separately
    let cmd_damage = app.world.get::<CommanderDamage>(player).unwrap();
    assert_eq!(cmd_damage.get_damage(commander1), 5);
    assert_eq!(cmd_damage.get_damage(commander2), 3);
    assert_eq!(cmd_damage.total_damage(), 8);
    
    // Player's health should also be reduced
    let health = app.world.get::<Health>(player).unwrap();
    assert_eq!(health.current, 32); // 40 - 5 - 3 = 32
    
    // More damage from commander1 in a later combat
    app.world.entity_mut(commander1).insert(
        DamageEvent {
            source: commander1,
            target: player,
            amount: 5,
            is_combat_damage: true,
        }
    );
    
    // Process the damage
    app.update();
    
    // Check state-based actions after damage
    app.update();
    
    // Verify commander damage accumulated correctly
    let cmd_damage_after = app.world.get::<CommanderDamage>(player).unwrap();
    assert_eq!(cmd_damage_after.get_damage(commander1), 10);
    assert_eq!(cmd_damage_after.get_damage(commander2), 3);
    
    // Verify player still alive (no commander has dealt 21+ damage yet)
    assert!(app.world.entity(player).contains::<Health>());
    
    // Deal more damage from commander1 to reach lethal commander damage
    app.world.entity_mut(commander1).insert(
        DamageEvent {
            source: commander1,
            target: player,
            amount: 11,
            is_combat_damage: true,
        }
    );
    
    // Process the damage
    app.update();
    
    // Check state-based actions after damage
    app.update();
    
    // Verify player lost due to commander damage
    let cmd_damage_final = app.world.get::<CommanderDamage>(player).unwrap();
    assert_eq!(cmd_damage_final.get_damage(commander1), 21);
    assert!(app.world.entity(player).contains::<PlayerEliminated>());
}
}

Test: Commander Damage from Copied Commander

#![allow(unused)]
fn main() {
#[test]
fn test_commander_damage_from_clone() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (combat_damage_system, clone_effects_system));
       
    // Create player
    let player = app.world.spawn((
        Player {},
        Health { current: 40, maximum: 40 },
        CommanderDamage::default(),
    )).id();
    
    // Create commander
    let commander = app.world.spawn((
        Creature { power: 5, toughness: 5 },
        Commander { owner: opponent },
        CreatureCard { controller: opponent },
    )).id();
    
    let opponent = app.world.spawn(Player {}).id();
    
    // Create clone of the commander
    let clone = app.world.spawn((
        Creature { power: 5, toughness: 5 },
        CloneEffect { source: commander },
        CreatureCard { controller: opponent },
    )).id();
    
    // Make clone attack
    app.world.entity_mut(clone).insert(Attacking { defending: player });
    
    // Process combat damage
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::CombatDamage);
    app.update();
    
    // Verify damage from clone is NOT commander damage
    let cmd_damage = app.world.get::<CommanderDamage>(player).unwrap();
    assert_eq!(cmd_damage.get_damage(commander), 0);
    assert_eq!(cmd_damage.get_damage(clone), 0);
    
    // Player's health should still be reduced
    let health = app.world.get::<Health>(player).unwrap();
    assert_eq!(health.current, 35); // 40 - 5 = 35
}
}

Test Case: Commander Combat Abilities

Test: Commander with Partner

#![allow(unused)]
fn main() {
#[test]
fn test_partner_commanders_in_combat() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (combat_damage_system, state_based_actions_system));
       
    // Create player
    let player = app.world.spawn((
        Player {},
        Health { current: 40, maximum: 40 },
        CommanderDamage::default(),
    )).id();
    
    // Create partner commanders
    let partner1 = app.world.spawn((
        Creature { power: 3, toughness: 3 },
        Commander { owner: opponent },
        Partner {},
        Attacking { defending: player },
    )).id();
    
    let partner2 = app.world.spawn((
        Creature { power: 2, toughness: 2 },
        Commander { owner: opponent },
        Partner {},
        Attacking { defending: player },
    )).id();
    
    let opponent = app.world.spawn(Player {}).id();
    
    // Process combat damage
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::CombatDamage);
    app.update();
    
    // Verify commander damage was tracked separately for each partner
    let cmd_damage = app.world.get::<CommanderDamage>(player).unwrap();
    assert_eq!(cmd_damage.get_damage(partner1), 3);
    assert_eq!(cmd_damage.get_damage(partner2), 2);
    
    // Player needs to take 21 damage from a single partner to lose
    // Simulate multiple combats to test this
    for _ in 0..6 {
        app.world.entity_mut(partner1).insert(
            DamageEvent {
                source: partner1,
                target: player,
                amount: 3,
                is_combat_damage: true,
            }
        );
        app.update();
    }
    
    // Check state-based actions
    app.update();
    
    // Verify player lost due to commander damage from one partner
    let cmd_damage_final = app.world.get::<CommanderDamage>(player).unwrap();
    assert_eq!(cmd_damage_final.get_damage(partner1), 21);
    assert!(app.world.entity(player).contains::<PlayerEliminated>());
}
}

Test: Commander with Combat Damage Triggers

#![allow(unused)]
fn main() {
#[test]
fn test_commander_combat_damage_triggers() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (combat_damage_system, trigger_system));
       
    // Create player
    let player = app.world.spawn((
        Player {},
        Health { current: 40, maximum: 40 },
        CommanderDamage::default(),
    )).id();
    
    // Create commander with combat damage trigger
    let commander = app.world.spawn((
        Creature { power: 5, toughness: 5 },
        Commander { owner: opponent },
        Attacking { defending: player },
        CombatDamageTrigger { 
            effect: TriggerEffect::DrawCards { 
                player: opponent,
                count: 1,
            }
        },
    )).id();
    
    let opponent = app.world.spawn((
        Player {},
        Library { cards: vec![card1, card2, card3] },
        Hand { cards: vec![] },
    )).id();
    
    let card1 = app.world.spawn(Card {}).id();
    let card2 = app.world.spawn(Card {}).id();
    let card3 = app.world.spawn(Card {}).id();
    
    // Process combat damage
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::CombatDamage);
    app.update();
    
    // Process triggers
    app.update();
    
    // Verify commander damage was tracked
    let cmd_damage = app.world.get::<CommanderDamage>(player).unwrap();
    assert_eq!(cmd_damage.get_damage(commander), 5);
    
    // Verify combat damage trigger resolved
    let hand = app.world.get::<Hand>(opponent).unwrap();
    assert_eq!(hand.cards.len(), 1);
}
}

Test Case: Multiplayer Combat Scenarios

Test: Attacking Multiple Players with Commander

#![allow(unused)]
fn main() {
#[test]
fn test_attacking_multiple_players_with_commander() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (declare_attackers_system, combat_damage_system));
       
    // Create players
    let player1 = app.world.spawn((
        Player {},
        Health { current: 40, maximum: 40 },
        CommanderDamage::default(),
    )).id();
    
    let player2 = app.world.spawn((
        Player {},
        Health { current: 40, maximum: 40 },
        CommanderDamage::default(),
    )).id();
    
    let active_player = app.world.spawn((
        Player {},
        ActivePlayer {},
    )).id();
    
    // Create commander with vigilance (can attack multiple players)
    let commander = app.world.spawn((
        Creature { power: 5, toughness: 5 },
        Commander { owner: active_player },
        CreatureCard { controller: active_player },
        Vigilance {},
    )).id();
    
    // Create additional attacker
    let other_attacker = app.world.spawn((
        Creature { power: 3, toughness: 3 },
        CreatureCard { controller: active_player },
    )).id();
    
    // Declare attackers for different players
    app.world.resource_mut::<AttackDeclaration>().declare_attacker(commander, player1);
    app.world.resource_mut::<AttackDeclaration>().declare_attacker(other_attacker, player2);
    
    // Process declare attackers
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::DeclareAttackers);
    app.update();
    
    // Process combat damage
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::CombatDamage);
    app.update();
    
    // Verify commander damage was tracked for player1 only
    let cmd_damage1 = app.world.get::<CommanderDamage>(player1).unwrap();
    assert_eq!(cmd_damage1.get_damage(commander), 5);
    
    let cmd_damage2 = app.world.get::<CommanderDamage>(player2).unwrap();
    assert_eq!(cmd_damage2.get_damage(commander), 0);
    
    // Verify health reduction for both players
    let health1 = app.world.get::<Health>(player1).unwrap();
    assert_eq!(health1.current, 35); // 40 - 5 = 35
    
    let health2 = app.world.get::<Health>(player2).unwrap();
    assert_eq!(health2.current, 37); // 40 - 3 = 37
}
}

Test: Goad Effect on Commander

#![allow(unused)]
fn main() {
#[test]
fn test_goaded_commander() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (declare_attackers_system, attack_restrictions_system));
       
    // Create players
    let player1 = app.world.spawn(Player {}).id();
    let player2 = app.world.spawn(Player {}).id();
    let player3 = app.world.spawn(Player {}).id();
    
    // Create commander that's been goaded by player2
    let commander = app.world.spawn((
        Creature { power: 5, toughness: 5 },
        Commander { owner: player1 },
        CreatureCard { controller: player1 },
        Goad { goaded_by: player2 },
    )).id();
    
    // Set up attack validation
    app.world.resource_mut::<TurnManager>().active_player = player1;
    app.world.resource_mut::<CombatSystem>().validate_attack = |attacker, defender, world| {
        // Basic validation - can't attack yourself
        let creature_card = world.get::<CreatureCard>(attacker).unwrap();
        if creature_card.controller == defender {
            return Err(AttackError::IllegalTarget);
        }
        
        // Check goad restrictions
        if let Some(goad) = world.get::<Goad>(attacker) {
            if goad.goaded_by != defender && defender != player3 {
                return Err(AttackError::MustAttackGoader);
            }
        }
        
        Ok(())
    };
    
    // Try to attack player3 (allowed because not the goader)
    assert!(app.world.resource::<CombatSystem>()
        .validate_attack(commander, player3, &app.world)
        .is_ok());
    
    // Try to attack player2 (allowed because this is the goader)
    assert!(app.world.resource::<CombatSystem>()
        .validate_attack(commander, player2, &app.world)
        .is_ok());
    
    // Try to attack self (not allowed)
    assert!(app.world.resource::<CombatSystem>()
        .validate_attack(commander, player1, &app.world)
        .is_err());
    
    // Commander must attack if able
    app.world.resource_mut::<AttackRequirements>().creatures_that_must_attack.push(commander);
    
    // Process attack requirements
    app.update();
    
    // Verify commander is forced to attack
    assert!(app.world.get::<MustAttack>(commander).is_some());
}
}

Test Case: Commander Zone Interactions

Test: Combat Damage Sending Commander to Command Zone

#![allow(unused)]
fn main() {
#[test]
fn test_commander_to_command_zone_from_combat() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (combat_damage_system, state_based_actions_system, zone_change_system));
       
    // Create commander
    let commander = app.world.spawn((
        Creature { power: 3, toughness: 3 },
        Commander { owner: player },
        CreatureCard { controller: player },
        Health { current: 3, maximum: 3 },
    )).id();
    
    let player = app.world.spawn((
        Player {},
        CommandZone { commanders: vec![] },
    )).id();
    
    // Create attacking creature
    let attacker = app.world.spawn((
        Creature { power: 5, toughness: 5 },
        Attacking { defending: player },
    )).id();
    
    // Make commander block
    app.world.entity_mut(commander).insert(
        Blocking { blocked_attackers: vec![attacker] }
    );
    
    // Process combat damage
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::CombatDamage);
    app.update();
    
    // Check state-based actions - commander should die from damage
    app.update();
    
    // Player should be prompted to send commander to command zone
    // We'll simulate them choosing to do so
    app.world.spawn(
        ZoneChangeRequest {
            entity: commander,
            from: Zone::Battlefield,
            to: Zone::CommandZone,
            reason: ZoneChangeReason::Death,
        }
    );
    
    // Process zone change
    app.update();
    
    // Verify commander is in command zone
    assert!(!app.world.entity(commander).contains::<Health>());
    assert!(!app.world.entity(commander).contains::<Blocking>());
    
    let command_zone = app.world.get::<CommandZone>(player).unwrap();
    assert!(command_zone.commanders.contains(&commander));
}
}

Test: Combat with Commander from Command Zone

#![allow(unused)]
fn main() {
#[test]
fn test_cast_commander_from_command_zone() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (cast_from_command_zone_system, declare_attackers_system));
       
    // Create player
    let player = app.world.spawn((
        Player {},
        Mana { 
            white: 5, blue: 5, black: 5, red: 5, green: 5, colorless: 5,
        },
        CommandZone { commanders: vec![commander] },
    )).id();
    
    // Create commander in command zone
    let commander = app.world.spawn((
        Commander { owner: player },
        CreatureCard { controller: player },
        ManaCost {
            white: 0, blue: 0, black: 0, red: 0, green: 0, colorless: 4,
            additional_cost: 0, // No command tax yet
        },
        InZone { zone: Zone::CommandZone },
    )).id();
    
    // Cast commander from command zone
    app.world.spawn(
        CastRequest {
            card: commander,
            controller: player,
            from_zone: Zone::CommandZone,
        }
    );
    
    // Process casting
    app.update();
    
    // Commander should now be on battlefield
    assert!(app.world.entity(commander).contains::<Creature>());
    assert_eq!(app.world.get::<InZone>(commander).unwrap().zone, Zone::Battlefield);
    
    // Verify mana was spent
    let mana_after = app.world.get::<Mana>(player).unwrap();
    assert_eq!(mana_after.colorless, 1); // 5 - 4 = 1
    
    // Declare commander as attacker
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::DeclareAttackers);
    app.world.resource_mut::<TurnManager>().active_player = player;
    
    app.world.resource_mut::<AttackDeclaration>().declare_attacker(commander, Entity::PLACEHOLDER);
    
    // Process declare attackers
    app.update();
    
    // Verify commander is attacking
    assert!(app.world.entity(commander).contains::<Attacking>());
}
}

Test Case: Commander Damage Edge Cases

Test: Commander Damage After Death and Recast

#![allow(unused)]
fn main() {
#[test]
fn test_commander_damage_after_recast() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (combat_damage_system, zone_change_system, cast_from_command_zone_system));
       
    // Create player
    let target_player = app.world.spawn((
        Player {},
        Health { current: 40, maximum: 40 },
        CommanderDamage::default(),
    )).id();
    
    // Create commander owner
    let commander_owner = app.world.spawn((
        Player {},
        Mana { 
            white: 10, blue: 10, black: 10, red: 10, green: 10, colorless: 10,
        },
        CommandZone { commanders: vec![] },
    )).id();
    
    // Create commander
    let commander = app.world.spawn((
        Creature { power: 5, toughness: 5 },
        Commander { owner: commander_owner },
        CreatureCard { controller: commander_owner },
        InZone { zone: Zone::Battlefield },
        ManaCost {
            white: 0, blue: 0, black: 0, red: 0, green: 0, colorless: 5,
            additional_cost: 0,
        },
    )).id();
    
    // Deal commander damage
    app.world.entity_mut(commander).insert(Attacking { defending: target_player });
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::CombatDamage);
    app.update();
    
    // Verify initial commander damage
    let cmd_damage1 = app.world.get::<CommanderDamage>(target_player).unwrap();
    assert_eq!(cmd_damage1.get_damage(commander), 5);
    
    // Commander dies
    app.world.spawn(
        ZoneChangeRequest {
            entity: commander,
            from: Zone::Battlefield,
            to: Zone::CommandZone,
            reason: ZoneChangeReason::Death,
        }
    );
    
    // Process zone change
    app.update();
    
    // Update command zone
    app.world.entity_mut(commander_owner).insert(
        CommandZone { commanders: vec![commander] }
    );
    
    // Update commander in command zone
    app.world.entity_mut(commander).insert(
        InZone { zone: Zone::CommandZone }
    );
    
    // Cast commander from command zone (now with command tax)
    app.world.entity_mut(commander).insert(
        ManaCost {
            white: 0, blue: 0, black: 0, red: 0, green: 0, colorless: 5,
            additional_cost: 2, // Command tax
        }
    );
    
    app.world.spawn(
        CastRequest {
            card: commander,
            controller: commander_owner,
            from_zone: Zone::CommandZone,
        }
    );
    
    // Process casting
    app.update();
    
    // Commander should be back on battlefield
    assert_eq!(app.world.get::<InZone>(commander).unwrap().zone, Zone::Battlefield);
    
    // Deal more commander damage
    app.world.entity_mut(commander).insert(Attacking { defending: target_player });
    app.update();
    
    // Verify commander damage accumulates even after recasting
    let cmd_damage2 = app.world.get::<CommanderDamage>(target_player).unwrap();
    assert_eq!(cmd_damage2.get_damage(commander), 10); // 5 + 5 = 10
}
}

Test: Commander Damage Through Redirect Effects

#![allow(unused)]
fn main() {
#[test]
fn test_commander_damage_with_redirect() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (combat_damage_system, replacement_effects_system));
       
    // Create players
    let player1 = app.world.spawn((
        Player {},
        Health { current: 40, maximum: 40 },
        CommanderDamage::default(),
    )).id();
    
    let player2 = app.world.spawn((
        Player {},
        Health { current: 40, maximum: 40 },
        CommanderDamage::default(),
        DamageReplacementEffect { 
            effect_type: ReplacementType::Redirect { 
                percentage: 100,
                target: TargetType::Player(player3),
                round_up: true,
            }
        },
    )).id();
    
    let player3 = app.world.spawn((
        Player {},
        Health { current: 40, maximum: 40 },
        CommanderDamage::default(),
    )).id();
    
    // Create commander
    let commander = app.world.spawn((
        Creature { power: 5, toughness: 5 },
        Commander { owner: player1 },
        CreatureCard { controller: player1 },
        Attacking { defending: player2 },
    )).id();
    
    // Process combat damage
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::CombatDamage);
    app.update();
    
    // Verify damage was redirected
    let health2 = app.world.get::<Health>(player2).unwrap();
    assert_eq!(health2.current, 40); // No damage taken
    
    let health3 = app.world.get::<Health>(player3).unwrap();
    assert_eq!(health3.current, 35); // 40 - 5 = 35
    
    // Verify commander damage is tracked for the final recipient
    let cmd_damage3 = app.world.get::<CommanderDamage>(player3).unwrap();
    assert_eq!(cmd_damage3.get_damage(commander), 5);
    
    // Original target should not have commander damage
    let cmd_damage2 = app.world.get::<CommanderDamage>(player2).unwrap();
    assert_eq!(cmd_damage2.get_damage(commander), 0);
}
}

Performance Considerations for Commander Combat Tests

1. Efficient Commander Damage Tracking: Optimize how commander damage is tracked and accumulated.

2. Zone Change Optimizations: Efficiently handle commander zone changes during and after combat.

3. Multiplayer Combat Performance: Ensure combat involving multiple players remains performant.

Test Coverage Checklist

• Multiple sources of commander damage tracking
• Commander damage from clones/copies
• Partner commanders in combat
• Combat damage triggers from commanders
• Attacking multiple players with a commander
• Goaded commanders
• Commander dying in combat and going to command zone
• Casting commander from command zone for combat
• Commander damage persistence after recasting
• Commander damage with redirection effects

Additional Commander-Specific Edge Cases

1. Multiple copies of the same commander (from Clone effects)
2. Commanders with alternate combat damage effects (infect, wither)
3. Face-down commanders (via Morph or similar effects)
4. Commander damage with replacement effects (damage doubling)
5. "Voltron" strategies with heavily equipped/enchanted commanders

Complex Combat Edge Cases - Test Documentation

Overview

This document outlines test cases for complex interactions in combat that involve multiple mechanics working together. These scenarios test the robustness of our Commander engine when dealing with intricate card interactions and edge cases.

Test Case: Multiple Triggers During Combat

Test: Death Triggers During Combat

#![allow(unused)]
fn main() {
#[test]
fn test_multiple_death_triggers_during_combat() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (combat_damage_system, trigger_system, state_based_actions_system));
       
    // Create creatures with death triggers
    let creature1 = app.world.spawn((
        Creature { power: 3, toughness: 3 },
        Attacking { defending: defender_entity },
        Health { current: 3, maximum: 3 },
        DiesTrigger { 
            effect: TriggerEffect::DealDamage { 
                amount: 2,
                target: TargetType::Player(defender_entity),
            }
        },
    )).id();
    
    let creature2 = app.world.spawn((
        Creature { power: 3, toughness: 3 },
        Blocking { blocked_attackers: vec![creature1] },
        Health { current: 3, maximum: 3 },
        DiesTrigger { 
            effect: TriggerEffect::GainLife { 
                amount: 2,
                target: TargetType::Player(controller_entity),
            }
        },
    )).id();
    
    let defender_entity = app.world.spawn((
        Player {},
        Health { current: 20, maximum: 20 },
    )).id();
    
    let controller_entity = app.world.spawn((
        Player {},
        Health { current: 20, maximum: 20 },
    )).id();
    
    // Process combat damage
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::CombatDamage);
    app.update();
    
    // Check state-based actions
    app.update();
    
    // Process death triggers
    app.update();
    
    // Verify both creatures died
    assert!(app.world.get::<Health>(creature1).is_none());
    assert!(app.world.get::<Health>(creature2).is_none());
    
    // Verify both death triggers resolved
    let defender_health = app.world.get::<Health>(defender_entity).unwrap();
    assert_eq!(defender_health.current, 18); // 20 - 2 from death trigger
    
    let controller_health = app.world.get::<Health>(controller_entity).unwrap();
    assert_eq!(controller_health.current, 22); // 20 + 2 from death trigger
}
}

Test Case: Replacement Effects During Combat

Test: Damage Prevention/Redirection

#![allow(unused)]
fn main() {
#[test]
fn test_damage_replacement_effects() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (combat_damage_system, replacement_effects_system));
       
    // Create attacker and blocker
    let attacker = app.world.spawn((
        Creature { power: 5, toughness: 5 },
        Attacking { defending: defender_entity },
    )).id();
    
    let blocker = app.world.spawn((
        Creature { power: 3, toughness: 3 },
        Blocking { blocked_attackers: vec![attacker] },
        Health { current: 3, maximum: 3 },
        // Replacement effect: Redirect half of all damage to controller (rounded up)
        DamageReplacementEffect { 
            effect_type: ReplacementType::Redirect { 
                percentage: 50,
                target: TargetType::Player(controller_entity),
                round_up: true,
            }
        },
    )).id();
    
    let defender_entity = app.world.spawn((
        Player {},
        Health { current: 20, maximum: 20 },
    )).id();
    
    let controller_entity = app.world.spawn((
        Player {},
        Health { current: 20, maximum: 20 },
    )).id();
    
    // Process combat damage
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::CombatDamage);
    app.update();
    
    // Verify damage was redirected
    let blocker_health = app.world.get::<Health>(blocker).unwrap();
    assert_eq!(blocker_health.current, 1); // 3 - (5 - 3) = 1
    
    let controller_health = app.world.get::<Health>(controller_entity).unwrap();
    assert_eq!(controller_health.current, 17); // 20 - 3 (redirected damage) = 17
    
    // Verify attacker also took damage
    let attacker_health = app.world.get::<Health>(attacker).unwrap();
    assert_eq!(attacker_health.current, 2); // 5 - 3 = 2
}
}

Test Case: Layer-Dependent Effects

Test: Characteristic-Defining Abilities and Pump Spells

#![allow(unused)]
fn main() {
#[test]
fn test_layer_dependent_effects() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (spell_resolution_system, characteristic_layer_system));
       
    // Create creature with CDA (power/toughness equal to cards in hand)
    let creature = app.world.spawn((
        CreatureCard {},
        // Base power/toughness are handled in layer 7a
        CharacteristicDefiningAbility { 
            affects: Characteristic::PowerToughness,
            calculation: Box::new(|world, entity| {
                // We'll mock this for the test - cards in hand = 4
                let cards_in_hand = 4;
                (cards_in_hand, cards_in_hand)
            }),
        },
    )).id();
    
    // Process CDA to establish base power/toughness
    app.update();
    
    // Verify creature has power/toughness equal to cards in hand
    let creature_stats = app.world.get::<Creature>(creature).unwrap();
    assert_eq!(creature_stats.power, 4);
    assert_eq!(creature_stats.toughness, 4);
    
    // Cast pump spell (+2/+2) - this applies in layer 7c
    app.world.spawn((
        PumpSpell { 
            target: creature,
            power_bonus: 2,
            toughness_bonus: 2,
            duration: SpellDuration::EndOfTurn,
        },
        SpellOnStack {},
    ));
    
    // Resolve spell
    app.update();
    
    // Verify creature stats were boosted correctly
    let boosted_creature = app.world.get::<Creature>(creature).unwrap();
    assert_eq!(boosted_creature.power, 6);  // 4 + 2 = 6
    assert_eq!(boosted_creature.toughness, 6);  // 4 + 2 = 6
    
    // Discard a card - affects layer 7a CDA
    app.world.spawn(DiscardCardCommand {
        player: Entity::PLACEHOLDER,
        count: 1,
    });
    app.update();
    
    // Verify stats update correctly (CDA now sees 3 cards, then +2/+2 applies)
    let updated_creature = app.world.get::<Creature>(creature).unwrap();
    assert_eq!(updated_creature.power, 5);  // 3 + 2 = 5
    assert_eq!(updated_creature.toughness, 5);  // 3 + 2 = 5
}
}

Test Case: Changing Controllers During Combat

Test: Creature Changes Controller During Combat

#![allow(unused)]
fn main() {
#[test]
fn test_creature_changes_controller_during_combat() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (combat_damage_system, spell_resolution_system, controller_system));
       
    let player1 = app.world.spawn(Player {}).id();
    let player2 = app.world.spawn(Player {}).id();
    
    // Create attacking creature controlled by player 1
    let attacker = app.world.spawn((
        Creature { power: 3, toughness: 3 },
        Attacking { defending: player2 },
        CreatureCard { controller: player1 },
    )).id();
    
    // Cast control-changing spell before damage
    app.world.spawn((
        ControlChangeSpell { 
            target: attacker,
            new_controller: player2,
            duration: SpellDuration::EndOfTurn,
        },
        SpellOnStack {},
    ));
    
    // Resolve spell
    app.update();
    
    // Verify creature changed controllers
    let creature_card = app.world.get::<CreatureCard>(attacker).unwrap();
    assert_eq!(creature_card.controller, player2);
    
    // Process combat damage
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::CombatDamage);
    app.update();
    
    // Verify creature is still attacking the same player
    assert!(app.world.get::<Attacking>(attacker).is_some());
    assert_eq!(app.world.get::<Attacking>(attacker).unwrap().defending, player2);
    
    // Verify no damage was dealt (can't attack yourself)
    let player2_health = app.world.get::<Health>(player2).unwrap();
    assert_eq!(player2_health.current, player2_health.maximum);
}
}

Test Case: Triggered Abilities Affecting Combat

Test: Attack Triggers Modifying Other Creatures

#![allow(unused)]
fn main() {
#[test]
fn test_attack_trigger_modifying_combat() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (declare_attackers_system, trigger_system, combat_damage_system));
       
    let player1 = app.world.spawn(Player {}).id();
    let player2 = app.world.spawn(Player {
        health: Health { current: 20, maximum: 20 },
    }).id();
    
    // Create creature with attack trigger
    let battle_leader = app.world.spawn((
        Creature { power: 2, toughness: 2 },
        CreatureCard { controller: player1 },
        AttackTrigger { 
            effect: TriggerEffect::PumpCreatures { 
                target_filter: TargetFilter::Controlled { controller: player1 },
                power_bonus: 1,
                toughness_bonus: 1,
                duration: SpellDuration::EndOfTurn,
            }
        },
    )).id();
    
    // Create another creature that will benefit from the trigger
    let other_attacker = app.world.spawn((
        Creature { power: 2, toughness: 2 },
        CreatureCard { controller: player1 },
    )).id();
    
    // Declare attackers
    app.world.entity_mut(battle_leader).insert(Attacking { defending: player2 });
    app.world.entity_mut(other_attacker).insert(Attacking { defending: player2 });
    
    // Process attack triggers
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::DeclareAttackers);
    app.update();
    
    // Verify both creatures were boosted
    let battle_leader_stats = app.world.get::<Creature>(battle_leader).unwrap();
    assert_eq!(battle_leader_stats.power, 3);  // 2 + 1 = 3
    
    let other_attacker_stats = app.world.get::<Creature>(other_attacker).unwrap();
    assert_eq!(other_attacker_stats.power, 3);  // 2 + 1 = 3
    
    // Process combat damage
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::CombatDamage);
    app.update();
    
    // Verify damage with the boost
    let player2_health = app.world.get::<Health>(player2).unwrap();
    assert_eq!(player2_health.current, 14);  // 20 - 3 - 3 = 14
}
}

Test Case: Damage Doubling and Prevention Interactions

Test: Damage Doubling with Prevention Shield

#![allow(unused)]
fn main() {
#[test]
fn test_damage_doubling_with_prevention() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (combat_damage_system, replacement_effects_system));
       
    // Create attacker with damage doubling effect
    let attacker = app.world.spawn((
        Creature { power: 4, toughness: 4 },
        Attacking { defending: defender_entity },
        DamageReplacementEffect { 
            effect_type: ReplacementType::Double { 
                condition: DamageCondition::DealingCombatDamage,
            }
        },
    )).id();
    
    // Create defender with protection shield
    let defender_entity = app.world.spawn((
        Player {},
        Health { current: 20, maximum: 20 },
        PreventDamage {
            amount: 5,
            source_filter: None,
        },
    )).id();
    
    // Process combat damage
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::CombatDamage);
    app.update();
    
    // The original 4 damage is doubled to 8, then 5 is prevented
    let defender_health = app.world.get::<Health>(defender_entity).unwrap();
    assert_eq!(defender_health.current, 17);  // 20 - (8 - 5) = 17
}
}

Test Case: Indestructible in Combat

Test: Indestructible Creature with Lethal Damage

#![allow(unused)]
fn main() {
#[test]
fn test_indestructible_with_lethal_damage() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (combat_damage_system, state_based_actions_system));
       
    // Create indestructible attacker
    let indestructible_attacker = app.world.spawn((
        Creature { power: 4, toughness: 4 },
        Attacking { defending: defender_entity },
        Health { current: 4, maximum: 4 },
        Indestructible {},
    )).id();
    
    // Create blocker with deathtouch
    let deathtouch_blocker = app.world.spawn((
        Creature { power: 1, toughness: 1 },
        Blocking { blocked_attackers: vec![indestructible_attacker] },
        Health { current: 1, maximum: 1 },
        Deathtouch {},
    )).id();
    
    let defender_entity = app.world.spawn((
        Player {},
        Health { current: 20, maximum: 20 },
    )).id();
    
    // Process combat damage
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::CombatDamage);
    app.update();
    
    // Check state-based actions
    app.update();
    
    // Verify blocker died
    assert!(app.world.get::<Health>(deathtouch_blocker).is_none());
    
    // Verify indestructible attacker is damaged but alive
    let attacker_health = app.world.get::<Health>(indestructible_attacker).unwrap();
    assert_eq!(attacker_health.current, 3);  // 4 - 1 = 3
    assert!(app.world.entity(indestructible_attacker).contains::<Indestructible>());
    
    // Verify it can still be in further combats despite lethal deathtouch damage
    let attacker_health = app.world.get::<Health>(indestructible_attacker).unwrap();
    app.world.entity_mut(indestructible_attacker).insert(
        DamageReceived {
            amount: 10,
            source: deathtouch_blocker,
            is_combat_damage: true,
        }
    );
    
    // Process more damage
    app.update();
    
    // Check state-based actions
    app.update();
    
    // Verify indestructible creature is still alive despite lethal damage
    assert!(app.world.get::<Health>(indestructible_attacker).is_some());
}
}

Test Case: Phasing and Pump Spell Interactions

Test: Phasing Out After Pump Spell

#![allow(unused)]
fn main() {
#[test]
fn test_phasing_after_pump_spell() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (spell_resolution_system, phasing_system, end_of_turn_system));
       
    // Create creature
    let creature = app.world.spawn((
        Creature { power: 2, toughness: 2 },
        CreatureCard {},
    )).id();
    
    // Cast pump spell
    app.world.spawn((
        PumpSpell { 
            target: creature,
            power_bonus: 2,
            toughness_bonus: 2,
            duration: SpellDuration::EndOfTurn,
        },
        SpellOnStack {},
    ));
    
    // Resolve spell
    app.update();
    
    // Verify creature stats were boosted
    let boosted_creature = app.world.get::<Creature>(creature).unwrap();
    assert_eq!(boosted_creature.power, 4);
    assert_eq!(boosted_creature.toughness, 4);
    
    // Phase out the creature
    app.world.entity_mut(creature).insert(PhasedOut {});
    
    // Process end of turn
    app.world.resource_mut::<TurnManager>().current_phase = Phase::End(EndPhaseStep::End);
    app.update();
    
    // The creature is phased out, so end of turn effects shouldn't affect it
    
    // Phase the creature back in
    app.world.entity_mut(creature).remove::<PhasedOut>();
    
    // Now the pump effect should still be active (since it didn't wear off while phased out)
    let still_boosted = app.world.get::<Creature>(creature).unwrap();
    assert_eq!(still_boosted.power, 4);
    assert_eq!(still_boosted.toughness, 4);
    
    // Process another end of turn
    app.update();
    
    // Now the effect should expire
    let end_of_turn = app.world.get::<Creature>(creature).unwrap();
    assert_eq!(end_of_turn.power, 2);
    assert_eq!(end_of_turn.toughness, 2);
}
}

Performance Considerations for Edge Case Tests

1. Efficient Interaction Processing: Ensure complex interaction processing is optimized.

2. Minimize Redundant Query Operations: Structure queries to minimize redundant operations.

3. Layer System Optimization: Efficiently process layer-dependent effects in the correct order.

Test Coverage Checklist

• Multiple death triggers during combat
• Damage replacement/redirection effects
• Layer-dependent ability interactions
• Controller change during combat
• Attack triggers modifying other creatures
• Damage doubling with prevention
• Indestructible creatures with lethal damage
• Phasing and pump spell interactions

Additional Considerations

1. Tests should verify both immediate effects and downstream consequences
2. Multiple mechanics should be tested in combination to ensure correct interactions
3. Order-dependent effects should be tested with different sequencing
4. Extreme edge cases should be included to stress-test the system

Combat Phasing Tests

This section contains tests for phasing effects during combat in the Commander format.

Tests

Phasing During Combat

Tests for how phasing effects interact with various stages of combat, including:

• Attackers phasing out after being declared
• Blockers phasing out after being declared
• Permanents with combat-relevant abilities phasing out
• Phasing effects on auras and equipment attached to creatures in combat
• Phasing and combat damage
• Phasing interaction with combat triggers

These tests ensure that the complex rules interactions between phasing and combat are handled correctly within the game engine.

Phasing During Combat - Test Cases

Overview

Phasing is a complex mechanic where permanents temporarily leave and re-enter the game without triggering "leaves the battlefield" or "enters the battlefield" effects. When a creature phases out during combat, several edge cases can occur that require special handling.

This document outlines test cases for phasing interactions during combat in our Commander engine.

Test Case: Attacker Phases Out

Test: Attacking Creature Phases Out During Declare Attackers

#![allow(unused)]
fn main() {
#[test]
fn test_attacker_phases_out_after_declare_attackers() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (declare_attackers_system, phasing_system));
       
    // Create attacker and defending player
    let attacker = app.world.spawn((
        Creature { power: 3, toughness: 3, },
        Attacking { defending: defender_entity },
    )).id();
    
    let defender_entity = app.world.spawn((
        Player {},
        Health { current: 20, maximum: 20 },
    )).id();
    
    // Phase out the attacker
    app.world.spawn(PhaseOutCommand { target: attacker });
    
    // Process phasing
    app.update();
    
    // Verify the creature is phased out but still marked as attacking
    assert!(app.world.get::<PhasedOut>(attacker).is_some());
    assert!(app.world.get::<Attacking>(attacker).is_some());
    
    // When combat damage is processed, it should not deal damage
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::CombatDamage);
    app.update();
    
    // Verify no damage was dealt to defender
    let health = app.world.get::<Health>(defender_entity).unwrap();
    assert_eq!(health.current, 20);
}
}

Test: Phased Out Attacker at End of Combat

#![allow(unused)]
fn main() {
#[test]
fn test_phased_out_attacker_at_end_of_combat() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (end_of_combat_system, phasing_system));
       
    // Create phased out attacker
    let attacker = app.world.spawn((
        Creature { power: 3, toughness: 3, },
        Attacking { defending: defender_entity },
        PhasedOut {},
    )).id();
    
    // Process end of combat
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::End);
    app.world.resource_mut::<CombatSystem>().end_of_combat.triggers_processed = true;
    app.update();
    
    // Verify attacking status is removed, even though creature is phased out
    assert!(!app.world.entity(attacker).contains::<Attacking>());
}
}

Test Case: Blocker Phases Out

Test: Blocking Creature Phases Out During Declare Blockers

#![allow(unused)]
fn main() {
#[test]
fn test_blocker_phases_out_after_declare_blockers() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (declare_blockers_system, phasing_system, combat_damage_system));
       
    // Create attacker, blocker, and player
    let attacker = app.world.spawn((
        Creature { power: 3, toughness: 3, },
        Attacking { defending: defender_entity },
    )).id();
    
    let blocker = app.world.spawn((
        Creature { power: 2, toughness: 2, },
        Blocking { blocked_attackers: vec![attacker] },
    )).id();
    
    let defender_entity = app.world.spawn((
        Player {},
        Health { current: 20, maximum: 20 },
    )).id();
    
    // Phase out the blocker
    app.world.spawn(PhaseOutCommand { target: blocker });
    
    // Process phasing
    app.update();
    
    // Verify the creature is phased out but still marked as blocking
    assert!(app.world.get::<PhasedOut>(blocker).is_some());
    assert!(app.world.get::<Blocking>(blocker).is_some());
    
    // When combat damage is processed, attacker should deal damage to player
    // since phased out blocker cannot block
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::CombatDamage);
    app.update();
    
    // Verify damage was dealt to defender (attacker was effectively unblocked)
    let health = app.world.get::<Health>(defender_entity).unwrap();
    assert_eq!(health.current, 17);
}
}

Test Case: Phasing During Combat Damage

Test: Creature Phases Out in Response to Damage

#![allow(unused)]
fn main() {
#[test]
fn test_creature_phases_out_in_response_to_damage() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (combat_damage_system, phasing_system));
       
    // Create attacker and blocker
    let attacker = app.world.spawn((
        Creature { power: 3, toughness: 3, },
        Attacking { defending: defender_entity },
    )).id();
    
    let blocker = app.world.spawn((
        Creature { power: 2, toughness: 2, },
        Blocking { blocked_attackers: vec![attacker] },
        Health { current: 2, maximum: 2 },
    )).id();
    
    // Simulate player responding to damage by phasing out the blocker
    // (in a real implementation, this would be triggered by priority passing)
    app.world.spawn(PhaseOutCommand { 
        target: blocker,
        trigger_condition: TriggerCondition::BeforeDamage,
    });
    
    // Process combat damage
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::CombatDamage);
    app.update();
    
    // Verify blocker phased out and did not receive damage
    assert!(app.world.get::<PhasedOut>(blocker).is_some());
    let health = app.world.get::<Health>(blocker).unwrap();
    assert_eq!(health.current, 2); // Health unchanged
    
    // Verify attacker did not receive damage either
    let attacker_health = app.world.get::<Health>(attacker).unwrap();
    assert_eq!(attacker_health.current, attacker_health.maximum);
}
}

Test Case: Phasing In During Combat

Test: Creature Phases In During Combat

#![allow(unused)]
fn main() {
#[test]
fn test_creature_phases_in_during_combat() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (phasing_system, combat_system));
       
    // Create phased out creature
    let creature = app.world.spawn((
        Creature { power: 3, toughness: 3, },
        PhasedOut {},
    )).id();
    
    // Set up phase in trigger for declare blockers step
    app.world.spawn(PhaseInCommand { 
        target: creature,
        trigger_phase: Phase::Combat(CombatStep::DeclareBlockers),
    });
    
    // Advance to declare blockers
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::DeclareBlockers);
    app.update();
    
    // Verify creature phased in
    assert!(app.world.get::<PhasedOut>(creature).is_none());
    
    // Verify creature cannot be declared as a blocker this combat
    // (creatures that phase in are treated as though they just entered the battlefield)
    let can_block = app.world.get_resource::<CombatSystem>().unwrap()
        .can_block(creature, attacker_entity);
    assert!(!can_block);
}
}

Test Case: Phasing with Auras and Equipment

Test: Equipped Creature Phases Out

#![allow(unused)]
fn main() {
#[test]
fn test_equipped_creature_phases_out_during_combat() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (phasing_system, combat_damage_system));
       
    // Create creature with equipment
    let creature = app.world.spawn((
        Creature { power: 2, toughness: 2, },
        Attacking { defending: defender_entity },
    )).id();
    
    let equipment = app.world.spawn((
        Equipment { 
            equipped_to: creature,
            power_bonus: 2,
            toughness_bonus: 0,
        },
        Attached { attached_to: creature },
    )).id();
    
    // Phase out the creature
    app.world.spawn(PhaseOutCommand { target: creature });
    app.update();
    
    // Verify creature and equipment are both phased out
    assert!(app.world.get::<PhasedOut>(creature).is_some());
    assert!(app.world.get::<PhasedOut>(equipment).is_some());
    
    // Process combat damage
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::CombatDamage);
    app.update();
    
    // Verify no damage was dealt
    let health = app.world.get::<Health>(defender_entity).unwrap();
    assert_eq!(health.current, 20);
    
    // Phase in during a later turn
    app.world.spawn(PhaseInCommand { 
        target: creature,
        trigger_phase: Phase::Main(MainPhaseStep::First),
    });
    
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Main(MainPhaseStep::First);
    app.update();
    
    // Verify both creature and equipment phased in and are still attached
    assert!(app.world.get::<PhasedOut>(creature).is_none());
    assert!(app.world.get::<PhasedOut>(equipment).is_none());
    assert_eq!(app.world.get::<Equipment>(equipment).unwrap().equipped_to, creature);
    assert_eq!(app.world.get::<Attached>(equipment).unwrap().attached_to, creature);
}
}

Integration with Turn Structure

Test: Phasing and Turn Phases

#![allow(unused)]
fn main() {
#[test]
fn test_phasing_respects_turn_structure() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (phasing_system, turn_system));
       
    // Create creature that phases out
    let creature = app.world.spawn((
        Creature { power: 3, toughness: 3, },
    )).id();
    
    // Phase out every other turn
    app.world.spawn(RecurringPhaseCommand { 
        target: creature,
        phase_out_on: TurnCondition::ActivePlayerTurn,
        phase_in_on: TurnCondition::NonActivePlayerTurn,
    });
    
    // Set active player
    app.world.resource_mut::<TurnManager>().active_player = player1_entity;
    app.update();
    
    // Verify creature is phased out on active player's turn
    assert!(app.world.get::<PhasedOut>(creature).is_some());
    
    // Change active player
    app.world.resource_mut::<TurnManager>().active_player = player2_entity;
    app.update();
    
    // Verify creature phases in on non-active player's turn
    assert!(app.world.get::<PhasedOut>(creature).is_none());
}
}

Performance Considerations for Phasing Tests

1. Batch Phasing Operations: Group phasing operations to minimize entity access.

2. Efficient Phase Tracking: Use a more efficient system for tracking phased entities.

3. Minimize Query Iterations: Structure queries to minimize iterations through phased entities.

Test Coverage Checklist

• Attackers phasing out during declare attackers
• Attackers phasing out during combat damage
• Blockers phasing out during declare blockers
• Blockers phasing out during combat damage
• Creatures phasing in during combat
• End of combat cleanup with phased entities
• Phasing with attached permanents (equipment, auras)
• Turn structure integration with phasing

Additional Edge Cases to Consider

1. Multiple creatures phasing in/out simultaneously
2. Phasing commander in and out (commander damage tracking)
3. Phasing and "enters the battlefield" replacement effects
4. Phasing and state-based actions

Combat Pump Spell Tests

This section contains tests for power and toughness modifying effects (pump spells) during combat in the Commander format.

Tests

Combat Pumps

Tests for how pump spells and similar effects interact with combat, including:

• Instant-speed pump spells after blockers are declared
• Pump effects that grant additional abilities (like first strike)
• Timing of pump effects and their impact on combat damage
• Interaction between multiple pump effects
• Pump effects that last until end of turn versus those with permanent effects
• Combat tricks that affect multiple creatures simultaneously

These tests ensure that power/toughness modification during combat is handled correctly according to the rules and timing of Magic: The Gathering.

Combat Pump Spells - Test Cases

Overview

Combat pump spells are instants that temporarily boost a creature's power and/or toughness, often used during combat to alter the outcome. These spells can be cast at various points during the combat phase, leading to different results depending on timing.

This document outlines test cases for combat pump spell interactions in our Commander engine.

Test Case: Basic Pump Spell Effects

Test: Power/Toughness Boost During Declare Blockers

#![allow(unused)]
fn main() {
#[test]
fn test_pump_spell_during_declare_blockers() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (declare_blockers_system, spell_resolution_system));
       
    // Create attacker and potential blocker
    let attacker = app.world.spawn((
        Creature { power: 4, toughness: 4 },
        Attacking { defending: defender_entity },
    )).id();
    
    let small_blocker = app.world.spawn((
        Creature { power: 1, toughness: 1 },
        CreatureCard { controller: defender_entity },
    )).id();
    
    let defender_entity = app.world.spawn((
        Player {},
        Health { current: 20, maximum: 20 },
    )).id();
    
    // Set up initially - blocker cannot block due to being too small
    app.world.resource_mut::<CombatSystem>().can_block_check = |blocker, attacker| {
        let blocker_creature = app.world.get::<Creature>(blocker).unwrap();
        let attacker_creature = app.world.get::<Creature>(attacker).unwrap();
        blocker_creature.power >= attacker_creature.power / 2
    };
    
    // Can't block initially
    let can_block_initially = app.world.resource::<CombatSystem>()
        .can_block(small_blocker, attacker);
    assert!(!can_block_initially);
    
    // Cast pump spell (+3/+3 until end of turn)
    app.world.spawn((
        PumpSpell { 
            target: small_blocker,
            power_bonus: 3,
            toughness_bonus: 3,
            duration: SpellDuration::EndOfTurn,
        },
        SpellOnStack {},
    ));
    
    // Resolve spell
    app.update();
    
    // Verify creature stats were boosted
    let boosted_creature = app.world.get::<Creature>(small_blocker).unwrap();
    assert_eq!(boosted_creature.power, 4);
    assert_eq!(boosted_creature.toughness, 4);
    
    // Now should be able to block
    let can_block_after = app.world.resource::<CombatSystem>()
        .can_block(small_blocker, attacker);
    assert!(can_block_after);
}
}

Test Case: Pump Spells During Combat Damage

Test: Pump Spell Saving Creature from Lethal Damage

#![allow(unused)]
fn main() {
#[test]
fn test_pump_spell_prevents_lethal_damage() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (combat_damage_system, spell_resolution_system));
       
    // Create attacker and blocker
    let attacker = app.world.spawn((
        Creature { power: 3, toughness: 3 },
        Attacking { defending: defender_entity },
    )).id();
    
    let blocker = app.world.spawn((
        Creature { power: 2, toughness: 2 },
        Blocking { blocked_attackers: vec![attacker] },
        Health { current: 2, maximum: 2 },
    )).id();
    
    // Before damage is dealt, cast pump spell to increase toughness
    // In a real implementation, this would be during the priority window
    app.world.spawn((
        PumpSpell { 
            target: blocker,
            power_bonus: 0,
            toughness_bonus: 2,
            duration: SpellDuration::EndOfTurn,
        },
        SpellOnStack {},
    ));
    
    // Resolve spell
    app.update();
    
    // Verify creature stats were boosted
    let boosted_creature = app.world.get::<Creature>(blocker).unwrap();
    assert_eq!(boosted_creature.power, 2);
    assert_eq!(boosted_creature.toughness, 4);
    
    // Process combat damage
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::CombatDamage);
    app.update();
    
    // Verify blocker survived
    let health = app.world.get::<Health>(blocker).unwrap();
    assert!(health.current > 0);
}
}

Test: Increasing Power After Blockers to Deal More Damage

#![allow(unused)]
fn main() {
#[test]
fn test_pump_spell_increases_damage_after_blockers() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (combat_damage_system, spell_resolution_system));
       
    // Create attacker and defending player
    let attacker = app.world.spawn((
        Creature { power: 2, toughness: 2 },
        Attacking { defending: defender_entity },
    )).id();
    
    let defender_entity = app.world.spawn((
        Player {},
        Health { current: 20, maximum: 20 },
    )).id();
    
    // After declare blockers, cast pump spell to increase power
    app.world.spawn((
        PumpSpell { 
            target: attacker,
            power_bonus: 3,
            toughness_bonus: 0,
            duration: SpellDuration::EndOfTurn,
        },
        SpellOnStack {},
    ));
    
    // Resolve spell
    app.update();
    
    // Verify creature stats were boosted
    let boosted_creature = app.world.get::<Creature>(attacker).unwrap();
    assert_eq!(boosted_creature.power, 5);
    
    // Process combat damage
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::CombatDamage);
    app.update();
    
    // Verify more damage was dealt to player
    let health = app.world.get::<Health>(defender_entity).unwrap();
    assert_eq!(health.current, 15); // 20 - 5 = 15
}
}

Test Case: Timing Edge Cases

Test: Pump Spell During First Strike Damage

#![allow(unused)]
fn main() {
#[test]
fn test_pump_spell_between_first_strike_and_normal_damage() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (first_strike_damage_system, combat_damage_system, spell_resolution_system));
       
    // Create first strike attacker and regular blocker
    let first_strike_attacker = app.world.spawn((
        Creature { power: 2, toughness: 2 },
        Attacking { defending: defender_entity },
        FirstStrike {},
    )).id();
    
    let regular_blocker = app.world.spawn((
        Creature { power: 2, toughness: 2 },
        Blocking { blocked_attackers: vec![first_strike_attacker] },
        Health { current: 2, maximum: 2 },
    )).id();
    
    // Process first strike damage
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::FirstStrike);
    app.update();
    
    // Verify blocker took damage but is still alive
    let health_after_first_strike = app.world.get::<Health>(regular_blocker).unwrap();
    assert_eq!(health_after_first_strike.current, 0);
    
    // SBA would normally destroy the creature here, but we'll simulate a pump spell in response
    // Cast Sudden Invigoration (instant that gives +0/+2 and prevents damage this turn)
    app.world.spawn((
        PumpSpell { 
            target: regular_blocker,
            power_bonus: 0,
            toughness_bonus: 2,
            duration: SpellDuration::EndOfTurn,
        },
        SpellOnStack {},
        PreventDamageEffect { amount: 2 },
    ));
    
    // Resolve spell and apply effects
    app.update();
    
    // Reset health as if the damage had been prevented
    app.world.entity_mut(regular_blocker).insert(Health { current: 2, maximum: 2 });
    
    // Verify creature stats were boosted and creature is alive
    let boosted_creature = app.world.get::<Creature>(regular_blocker).unwrap();
    assert_eq!(boosted_creature.toughness, 4);
    
    let health_after_spell = app.world.get::<Health>(regular_blocker).unwrap();
    assert_eq!(health_after_spell.current, 2);
    
    // Process regular combat damage
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::CombatDamage);
    app.update();
    
    // Verify blocker survived regular combat damage too
    let final_health = app.world.get::<Health>(regular_blocker).unwrap();
    assert_eq!(final_health.current, 2); // Damage was prevented
}
}

Test: Pump Spell at End of Combat

#![allow(unused)]
fn main() {
#[test]
fn test_pump_spell_at_end_of_combat() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (end_of_combat_system, spell_resolution_system));
       
    // Create creature
    let creature = app.world.spawn((
        Creature { power: 2, toughness: 2 },
        CreatureCard {},
    )).id();
    
    // Cast pump spell with "until end of turn" duration
    app.world.spawn((
        PumpSpell { 
            target: creature,
            power_bonus: 3,
            toughness_bonus: 3,
            duration: SpellDuration::EndOfTurn,
        },
        SpellOnStack {},
    ));
    
    // Resolve spell
    app.update();
    
    // Verify creature stats were boosted
    let boosted_creature = app.world.get::<Creature>(creature).unwrap();
    assert_eq!(boosted_creature.power, 5);
    assert_eq!(boosted_creature.toughness, 5);
    
    // Add EndOfTurn effect
    app.world.entity_mut(creature).insert(UntilEndOfTurn {
        original_power: 2,
        original_toughness: 2,
    });
    
    // Process end of combat phase
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::End);
    app.world.resource_mut::<CombatSystem>().end_of_combat.triggers_processed = true;
    app.update();
    
    // Verify creature stats still boosted after end of combat
    // (effects last until end of turn, not end of combat)
    let still_boosted = app.world.get::<Creature>(creature).unwrap();
    assert_eq!(still_boosted.power, 5);
    assert_eq!(still_boosted.toughness, 5);
    
    // Process end of turn
    app.world.resource_mut::<TurnManager>().current_phase = Phase::End(EndPhaseStep::End);
    app.update();
    
    // Now the effects should wear off
    let end_of_turn = app.world.get::<Creature>(creature).unwrap();
    assert_eq!(end_of_turn.power, 2);
    assert_eq!(end_of_turn.toughness, 2);
}
}

Test Case: Multiple Pump Spells

Test: Stacking Pump Effects

#![allow(unused)]
fn main() {
#[test]
fn test_stacking_pump_spells() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, spell_resolution_system);
       
    // Create creature
    let creature = app.world.spawn((
        Creature { power: 1, toughness: 1 },
        CreatureCard {},
    )).id();
    
    // Cast first pump spell
    app.world.spawn((
        PumpSpell { 
            target: creature,
            power_bonus: 2,
            toughness_bonus: 2,
            duration: SpellDuration::EndOfTurn,
        },
        SpellOnStack {},
    ));
    
    // Resolve first spell
    app.update();
    
    // Cast second pump spell
    app.world.spawn((
        PumpSpell { 
            target: creature,
            power_bonus: 1,
            toughness_bonus: 3,
            duration: SpellDuration::EndOfTurn,
        },
        SpellOnStack {},
    ));
    
    // Resolve second spell
    app.update();
    
    // Verify creature stats were properly stacked
    let boosted_creature = app.world.get::<Creature>(creature).unwrap();
    assert_eq!(boosted_creature.power, 4);  // 1 + 2 + 1 = 4
    assert_eq!(boosted_creature.toughness, 6);  // 1 + 2 + 3 = 6
}
}

Test Case: Pump Spells and Combat Abilities

Test: Pump Giving Trample

#![allow(unused)]
fn main() {
#[test]
fn test_pump_spell_gives_trample() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (combat_damage_system, spell_resolution_system));
       
    // Create attacker, blocker, and player
    let attacker = app.world.spawn((
        Creature { power: 4, toughness: 4 },
        Attacking { defending: defender_entity },
    )).id();
    
    let blocker = app.world.spawn((
        Creature { power: 2, toughness: 2 },
        Blocking { blocked_attackers: vec![attacker] },
        Health { current: 2, maximum: 2 },
    )).id();
    
    let defender_entity = app.world.spawn((
        Player {},
        Health { current: 20, maximum: 20 },
    )).id();
    
    // Cast pump spell that also grants trample
    app.world.spawn((
        PumpSpell { 
            target: attacker,
            power_bonus: 1,
            toughness_bonus: 1,
            duration: SpellDuration::EndOfTurn,
        },
        SpellOnStack {},
        GrantAbilityEffect { 
            ability: CreatureAbility::Trample,
            duration: SpellDuration::EndOfTurn,
        },
    ));
    
    // Resolve spell
    app.update();
    
    // Verify creature stats were boosted and gained trample
    let boosted_creature = app.world.get::<Creature>(attacker).unwrap();
    assert_eq!(boosted_creature.power, 5);
    assert!(app.world.get::<Trample>(attacker).is_some());
    
    // Process combat damage
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::CombatDamage);
    app.update();
    
    // Verify blocker is destroyed
    let blocker_health = app.world.get::<Health>(blocker).unwrap();
    assert_eq!(blocker_health.current, 0);
    
    // Verify excess damage trampled through to player
    let player_health = app.world.get::<Health>(defender_entity).unwrap();
    assert_eq!(player_health.current, 17); // 20 - (5-2) = 17
}
}

Test Case: Pump Spell Targeting

Test: Incorrectly Targeted Pump Spell

#![allow(unused)]
fn main() {
#[test]
fn test_illegally_targeted_pump_spell() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, spell_resolution_system);
       
    // Create creature with hexproof
    let hexproof_creature = app.world.spawn((
        Creature { power: 2, toughness: 2 },
        CreatureCard {},
        Hexproof {},
    )).id();
    
    // Create opposing player
    let opponent_entity = app.world.spawn(Player {}).id();
    
    // Cast pump spell from opponent (should fail due to hexproof)
    app.world.spawn((
        PumpSpell { 
            target: hexproof_creature,
            power_bonus: 2,
            toughness_bonus: 2,
            duration: SpellDuration::EndOfTurn,
        },
        SpellOnStack {},
        SpellController { controller: opponent_entity },
    ));
    
    // Attempt to resolve spell (should be countered by game rules)
    app.update();
    
    // Verify creature stats were not changed
    let creature = app.world.get::<Creature>(hexproof_creature).unwrap();
    assert_eq!(creature.power, 2);
    assert_eq!(creature.toughness, 2);
    
    // Verify spell was countered
    let spell_events = app.world.resource::<Events<SpellEvent>>().get_reader().iter().collect::<Vec<_>>();
    assert!(spell_events.iter().any(|event| matches!(event, SpellEvent::Countered(_))));
}
}

Integration with Combat System

Test: Pump Spells and State-Based Actions

#![allow(unused)]
fn main() {
#[test]
fn test_pump_spell_and_state_based_actions() {
    // Test setup
    let mut app = App::new();
    app.add_plugins(MinimalPlugins)
       .add_systems(Update, (spell_resolution_system, state_based_actions_system));
       
    // Create damaged creature
    let creature = app.world.spawn((
        Creature { power: 2, toughness: 2 },
        CreatureCard {},
        Health { current: 1, maximum: 2 },
    )).id();
    
    // Deal damage to creature
    app.world.entity_mut(creature).insert(DamageReceived {
        amount: 2,
        source: Entity::PLACEHOLDER,
        is_combat_damage: false,
    });
    
    // Process state-based actions to apply damage
    app.update();
    
    // Health would be 0, but don't destroy yet
    
    // Cast pump spell to increase toughness before SBA check
    app.world.spawn((
        PumpSpell { 
            target: creature,
            power_bonus: 0,
            toughness_bonus: 2,
            duration: SpellDuration::EndOfTurn,
        },
        SpellOnStack {},
        InstantEffect {},
    ));
    
    // Resolve spell
    app.update();
    
    // Verify creature stats were boosted
    let boosted_creature = app.world.get::<Creature>(creature).unwrap();
    assert_eq!(boosted_creature.toughness, 4);
    
    // Update health to reflect new toughness (would happen in a real implementation)
    app.world.entity_mut(creature).insert(Health {
        current: 1, // Still has damage marked
        maximum: 4,
    });
    
    // Verify creature is still alive despite the damage
    assert!(app.world.get::<Health>(creature).is_some());
    
    // Process state-based actions again
    app.update();
    
    // Verify creature is still alive
    assert!(app.world.get::<Health>(creature).is_some());
}
}

Performance Considerations for Pump Spell Tests

1. Optimize Spell Resolution: Structure spell resolution to minimize entity access.

2. Batch Effect Application: Group similar effects when applying multiple pump spells.

3. Efficient Stat Calculation: Use an efficient system for calculating final creature stats.

Test Coverage Checklist

• Basic pump spell application
• Pump spells preventing lethal damage
• Increasing power after blockers
• Pump spells during first strike damage
• Pump spells at end of combat
• Stacking multiple pump spells
• Pump spells granting abilities
• Invalid pump spell targeting
• Pump spells and state-based actions
• Pump spells with delayed effects

Additional Edge Cases to Consider

1. Pump spells with conditional effects
2. Pump spells that scale based on game state
3. Pump spells that trigger other abilities
4. Temporary control change plus pump effects
5. Layer-dependent pump effects (timestamps, dependencies)

Special Rules

This section covers special rules and mechanics unique to the Commander format.

Contents

• Multiplayer Politics - Voting, deals, and social mechanics
• Partner Commanders - Commander partners and related mechanics
• Commander Ninjutsu - The Commander Ninjutsu mechanic
• Commander Death Triggers - How commander death and zone changes work
• Commander-Specific Cards - Cards designed specifically for Commander

Commander-Specific Rules

The special rules section covers Commander-specific rules that are unique to the format:

Partners and Backgrounds

Partner mechanics allow players to have two commanders. There are several forms:

• Universal Partners: Any two commanders with "Partner" can be paired
• Partner With: Specific cards that can only partner with their named counterpart
• Background: Legendary creatures that "can have a Background" as a second commander
• Friends Forever: A variant of Partner that allows pairing any two "Friends Forever" cards

See Partner Commanders for implementation details.

Commander Ninjutsu

Commander Ninjutsu is a variant of the Ninjutsu mechanic that allows a commander to be put onto the battlefield from the command zone by returning an unblocked attacker to hand. This mechanic is currently only found on one card: Yuriko, the Tiger's Shadow.

See Commander Ninjutsu for implementation details.

Commander Death and Zone Changes

In Commander, when a commander would change zones, its owner can choose to move it to the command zone instead. Special rules govern how this interacts with "dies" triggers and other zone-change abilities.

See Commander Death Triggers for implementation details.

Commander-Specific Cards

Many cards have been designed specifically for the Commander format, including:

• Cards that reference the command zone directly
• Cards with mechanics only found in Commander products (Myriad, Lieutenant, etc.)
• Cards that affect the Commander tax
• Cards designed for multiplayer political play

See Commander-Specific Cards for implementation details.

Multiplayer Politics

Commander is often played as a multiplayer format, and certain mechanics are designed for multiplayer interactions:

• Voting mechanics
• Deal-making abilities
• Group effects that affect all players
• Incentives and deterrents for attacking

See Multiplayer Politics and Politics Testing for implementation details.

Related Mechanics

Some Commander-specific mechanics interact with other systems:

• Commander Damage - For tracking commander combat damage
• Command Zone - For commander zone transitions
• Commander Tax - For additional costs to cast commanders
• Color Identity - For deck construction restrictions

Testing Special Rules

The tests directory contains test cases for verifying the correct implementation of special Commander rules and edge case handling.

Multiplayer Politics

Overview

The Multiplayer Politics module handles the social and strategic elements unique to multiplayer Commander games. This includes deal-making, alliance formation, temporary agreements, voting mechanics, and other player interactions not codified in the standard Magic rules.

Core Features

The system includes:

• Deal Making System: Framework for players to propose, accept, and track in-game deals
• Voting Mechanics: Implementation of cards with Council's Dilemma, Will of the Council, and other voting abilities
• Threat Assessment: Tools to analyze and display relative threat levels of players
• Alliance Tracking: Temporary cooperative arrangements between players
• Table Talk Integration: Support for in-game communication with policy enforcement
• Goad Mechanics: Implementation of abilities that force creatures to attack

Implementation

The politics system is implemented through several interconnected components:

#![allow(unused)]
fn main() {
#[derive(Component)]
pub struct PoliticsComponent {
    // Current deals, alliances, and political state
    pub active_deals: Vec<Deal>,
    pub alliances: HashMap<Entity, AllianceStrength>,
    pub political_capital: f32,
    pub trust_level: HashMap<Entity, TrustLevel>,
    
    // Historical tracking
    pub broken_deals: Vec<BrokenDeal>,
    pub past_alliances: Vec<PastAlliance>,
}

#[derive(Resource)]
pub struct PoliticsSystem {
    // Global politics configuration
    pub enable_deals: bool,
    pub allow_secret_deals: bool,
    pub deal_enforcement_level: DealEnforcementLevel,
    
    // Event history
    pub political_events: VecDeque<PoliticalEvent>,
}
}

Deal Structure

Deals are structured entities that capture player agreements:

#![allow(unused)]
fn main() {
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct Deal {
    /// Unique identifier for the deal
    pub id: Uuid,
    /// Player who proposed the deal
    pub proposer: Entity,
    /// Player(s) who accepted the deal
    pub acceptors: Vec<Entity>,
    /// Terms of the deal - what each party agrees to do
    pub terms: Vec<DealTerm>,
    /// When the deal expires (if temporary)
    pub expiration: Option<DealExpiration>,
    /// Current status of the deal
    pub status: DealStatus,
    /// When the deal was created
    pub created_at: f64,
    /// When the deal was last updated
    pub last_updated: f64,
}

#[derive(Clone, Debug, Serialize, Deserialize)]
pub enum DealTerm {
    /// Promise not to attack a player for N turns
    NonAggression {
        target: Entity,
        duration: u32,
    },
    /// Promise to attack a specific player
    AttackPlayer {
        target: Entity,
        next_turn_only: bool,
    },
    /// Promise not to counter a player's next spell
    NoCounterspell {
        target: Entity,
        duration: u32,
    },
    /// Promise to share resources (e.g. let them draw when you draw)
    ShareResource {
        resource_type: ResourceType,
        target: Entity,
        amount: u32,
    },
    /// Promise to vote with a player on the next vote
    VoteAlignment {
        ally: Entity,
        vote_count: u32,
    },
    /// Custom term with free-form text
    Custom {
        description: String,
    },
}
}

Deal Making

The deal making system allows players to:

• Propose deals with specific terms and duration
• Accept or reject deals from other players
• Set automatic deal conditions and consequences
• Track deal fulfillment and violations

Deals are non-binding at the rules level but provide framework for player agreements.

#![allow(unused)]
fn main() {
/// System that handles deal proposals
pub fn handle_deal_proposals(
    mut commands: Commands,
    mut deal_events: EventReader<DealProposalEvent>,
    mut deal_response_events: EventWriter<DealResponseEvent>,
    mut politics_components: Query<&mut PoliticsComponent>,
) {
    for event in deal_events.read() {
        if let Ok(mut proposer_politics) = politics_components.get_mut(event.proposer) {
            // Create new deal
            let deal = Deal {
                id: Uuid::new_v4(),
                proposer: event.proposer,
                acceptors: Vec::new(),
                terms: event.terms.clone(),
                expiration: event.expiration.clone(),
                status: DealStatus::Proposed,
                created_at: event.timestamp,
                last_updated: event.timestamp,
            };
            
            // Add to proposer's active deals
            proposer_politics.active_deals.push(deal.clone());
            
            // Notify target players
            for target in &event.targets {
                deal_response_events.send(DealResponseEvent {
                    deal_id: deal.id,
                    response_type: DealResponseType::Offered,
                    player: *target,
                    timestamp: event.timestamp,
                });
            }
        }
    }
}

/// System that handles deal responses
pub fn handle_deal_responses(
    mut commands: Commands,
    mut deal_response_events: EventReader<DealResponseEvent>,
    mut politics_components: Query<&mut PoliticsComponent>,
    mut deal_update_events: EventWriter<DealUpdateEvent>,
) {
    for event in deal_response_events.read() {
        // Handle player responses to deals
        match event.response_type {
            DealResponseType::Accept => {
                // Update the deal status
                for (entity, mut politics) in politics_components.iter_mut() {
                    for deal in &mut politics.active_deals {
                        if deal.id == event.deal_id {
                            deal.acceptors.push(event.player);
                            deal.last_updated = event.timestamp;
                            
                            // If all targets have accepted, activate the deal
                            if deal.acceptors.len() >= deal.terms.len() {
                                deal.status = DealStatus::Active;
                                deal_update_events.send(DealUpdateEvent {
                                    deal_id: deal.id,
                                    new_status: DealStatus::Active,
                                    timestamp: event.timestamp,
                                });
                            }
                            
                            break;
                        }
                    }
                }
            },
            DealResponseType::Reject => {
                // Handle rejection
                for (entity, mut politics) in politics_components.iter_mut() {
                    for deal in &mut politics.active_deals {
                        if deal.id == event.deal_id {
                            deal.status = DealStatus::Rejected;
                            deal.last_updated = event.timestamp;
                            
                            deal_update_events.send(DealUpdateEvent {
                                deal_id: deal.id,
                                new_status: DealStatus::Rejected,
                                timestamp: event.timestamp,
                            });
                            
                            break;
                        }
                    }
                }
            },
            // Handle other response types
            _ => {}
        }
    }
}
}

Voting Mechanics

Many Commander-specific cards feature voting mechanics (Council's Dilemma, Will of the Council). The voting system handles these cards' abilities:

#![allow(unused)]
fn main() {
/// Component for cards with voting mechanics
#[derive(Component)]
pub struct VotingMechanic {
    /// The type of voting mechanic
    pub voting_type: VotingType,
    /// The available options to vote for
    pub options: Vec<String>,
    /// How the results are applied
    pub resolution: VoteResolutionMethod,
}

/// Types of voting mechanics
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum VotingType {
    /// Will of the Council - each player gets one vote
    WillOfCouncil,
    /// Council's Dilemma - each player votes for two different options
    CouncilsDilemma,
    /// Parley - a special voting variant
    Parley,
    /// Custom voting system
    Custom,
}

/// System for handling vote card resolution
pub fn handle_voting_resolution(
    mut commands: Commands,
    mut vote_events: EventReader<VoteCompletionEvent>,
    voting_cards: Query<(Entity, &VotingMechanic)>,
    players: Query<Entity, With<Player>>,
) {
    for event in vote_events.read() {
        if let Ok((card_entity, voting_mechanic)) = voting_cards.get(event.source_card) {
            // Collect and tally votes
            let mut vote_counts: HashMap<String, u32> = HashMap::new();
            
            for (player, vote) in &event.votes {
                *vote_counts.entry(vote.clone()).or_default() += 1;
            }
            
            // Apply effects based on voting results and resolution method
            match voting_mechanic.resolution {
                VoteResolutionMethod::MostVotes => {
                    // Find option with most votes
                    if let Some((winning_option, _)) = vote_counts
                        .iter()
                        .max_by_key(|(_, count)| *count) {
                        
                        // Apply effect for winning option
                        apply_voting_effect(
                            &mut commands, 
                            card_entity, 
                            winning_option, 
                            &event.votes
                        );
                    }
                },
                VoteResolutionMethod::AllVotes => {
                    // Apply effect for each vote
                    for (option, count) in vote_counts {
                        // Apply effect scaled by vote count
                        apply_voting_effect_scaled(
                            &mut commands,
                            card_entity,
                            &option,
                            count,
                            &event.votes
                        );
                    }
                },
                // Handle other resolution methods
                _ => {}
            }
        }
    }
}
}

Example Voting Card Implementation

#![allow(unused)]
fn main() {
/// Implementation of Councils' Judgment
pub fn create_councils_judgment() -> impl Bundle {
    (
        CardName("Council's Judgment".to_string()),
        CardType::Sorcery,
        ManaCost::parse("{1}{W}{W}"),
        VotingMechanic {
            voting_type: VotingType::WillOfCouncil,
            options: vec!["Exile".to_string()], // Dynamic: each nonland permanent becomes an option
            resolution: VoteResolutionMethod::MostVotes,
        },
        CouncilsJudgmentEffect,
    )
}

#[derive(Component)]
pub struct CouncilsJudgmentEffect;

impl ResolveEffect for CouncilsJudgmentEffect {
    fn resolve(&self, world: &mut World, source: Entity, controller: Entity) {
        // Get all permanents as potential targets
        let targets: Vec<Entity> = get_valid_permanent_targets(world);
        
        // Start voting process
        world.send_event(InitiateVoteEvent {
            source: source,
            voting_type: VotingType::WillOfCouncil,
            options: targets.iter().map(|e| get_name_for_entity(world, *e)).collect(),
            initiator: controller,
        });
    }
}
}

Threat Assessment

The threat assessment system helps players evaluate relative threats by:

• Displaying board state power metrics
• Tracking win proximity indicators
• Highlighting potential combo pieces
• Providing history of player actions and tendencies

#![allow(unused)]
fn main() {
/// Resource for tracking threat assessment
#[derive(Resource)]
pub struct ThreatAssessment {
    /// Calculated threat level for each player
    pub player_threats: HashMap<Entity, ThreatLevel>,
    /// Factors contributing to threat calculation
    pub threat_factors: HashMap<Entity, Vec<ThreatFactor>>,
    /// Historical threat trends
    pub threat_history: HashMap<Entity, VecDeque<HistoricalThreat>>,
}

/// System that updates threat assessment
pub fn update_threat_assessment(
    mut threat_assessment: ResMut<ThreatAssessment>,
    players: Query<Entity, With<Player>>,
    life_totals: Query<&LifeTotal>,
    permanents: Query<(Entity, &Controller)>,
    commanders: Query<(Entity, &Commander, &Controller)>,
    graveyards: Query<(&Graveyard, &Owner)>,
    hands: Query<(&Hand, &Owner)>,
) {
    // Update threat metrics for each player
    for player in players.iter() {
        let mut threat_factors = Vec::new();
        
        // Factor: Board presence
        let board_presence = permanents
            .iter()
            .filter(|(_, controller)| controller.0 == player)
            .count();
        
        threat_factors.push(ThreatFactor {
            factor_type: ThreatFactorType::BoardPresence,
            value: board_presence as f32 * 0.5,
        });
        
        // Factor: Commander damage potential
        if let Some((_, _, _)) = commanders
            .iter()
            .find(|(_, _, controller)| controller.0 == player) {
            // Calculate commander threat...
            threat_factors.push(ThreatFactor {
                factor_type: ThreatFactorType::CommanderPresence,
                value: 5.0, // Base threat for having commander
            });
        }
        
        // Calculate other factors...
        
        // Update total threat
        let total_threat = threat_factors.iter().map(|f| f.value).sum();
        
        threat_assessment.player_threats.insert(player, ThreatLevel(total_threat));
        threat_assessment.threat_factors.insert(player, threat_factors);
        
        // Update history
        threat_assessment.threat_history
            .entry(player)
            .or_default()
            .push_back(HistoricalThreat {
                level: ThreatLevel(total_threat),
                turn: get_current_turn(),
            });
    }
}
}

Goad Mechanics

Goad is a Commander-specific mechanic that forces creatures to attack:

#![allow(unused)]
fn main() {
/// Component for Goad effects
#[derive(Component)]
pub struct Goaded {
    /// The player who applied the goad effect
    pub goaded_by: Entity,
    /// When the goad effect expires
    pub expires_at: ExpiryTiming,
}

/// System that enforces Goad attack requirements
pub fn enforce_goad_attack_requirement(
    goaded_creatures: Query<(Entity, &Goaded, &Controller)>,
    mut attack_requirement_events: EventWriter<AttackRequirementEvent>,
    turn_manager: Res<TurnManager>,
) {
    // Only check during active player's combat
    if turn_manager.current_phase != Phase::Combat(CombatStep::DeclareAttackers) {
        return;
    }
    
    let active_player = turn_manager.active_player;
    
    // Find creatures controlled by active player that are goaded
    for (entity, goaded, controller) in goaded_creatures.iter() {
        if controller.0 == active_player {
            // Creature must attack if able, and cannot attack player who goaded it
            attack_requirement_events.send(AttackRequirementEvent {
                creature: entity,
                must_attack: true,
                cannot_attack: vec![goaded.goaded_by],
            });
        }
    }
}
}

Alliance Tracking

Alliances are temporary arrangements between players:

#![allow(unused)]
fn main() {
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct Alliance {
    /// Players in the alliance
    pub members: Vec<Entity>,
    /// Strength/type of alliance
    pub strength: AllianceStrength,
    /// Purpose of the alliance
    pub purpose: String,
    /// When the alliance was formed
    pub formed_at: f64,
    /// When the alliance expires (if temporary)
    pub expires_at: Option<f64>,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum AllianceStrength {
    /// Weak alliance of convenience
    Weak,
    /// Standard alliance
    Moderate,
    /// Strong alliance with significant shared interests
    Strong,
}

/// System for tracking and updating alliances
pub fn update_alliances(
    mut politics_components: Query<&mut PoliticsComponent>,
    time: Res<Time>,
    mut alliance_events: EventReader<AllianceEvent>,
) {
    let current_time = time.elapsed_seconds_f64();
    
    // Process alliance events
    for event in alliance_events.read() {
        match event.event_type {
            AllianceEventType::Form => {
                // Create new alliance
                let alliance = Alliance {
                    members: event.members.clone(),
                    strength: event.strength.clone(),
                    purpose: event.purpose.clone(),
                    formed_at: current_time,
                    expires_at: event.expiration,
                };
                
                // Update politics components for all members
                for member in &event.members {
                    if let Ok(mut politics) = politics_components.get_mut(*member) {
                        for other_member in &event.members {
                            if *other_member != *member {
                                politics.alliances.insert(*other_member, alliance.strength.clone());
                            }
                        }
                    }
                }
            },
            AllianceEventType::Break => {
                // Handle alliance breaking
                for member in &event.members {
                    if let Ok(mut politics) = politics_components.get_mut(*member) {
                        for other_member in &event.members {
                            if *other_member != *member {
                                politics.alliances.remove(other_member);
                                
                                // Record broken alliance in history
                                politics.past_alliances.push(PastAlliance {
                                    with: *other_member,
                                    strength: event.strength.clone(),
                                    purpose: event.purpose.clone(),
                                    formed_at: event.formed_at.unwrap_or(0.0),
                                    broken_at: current_time,
                                    broken_reason: event.reason.clone(),
                                });
                            }
                        }
                    }
                }
            },
        }
    }
    
    // Check for expired alliances
    for mut politics in politics_components.iter_mut() {
        // Implementation for alliance expiration...
    }
}
}

AI Integration

For games with AI opponents, the politics system:

• Models AI political decision making based on configured personalities
• Evaluates deal proposals based on game state and risk assessment
• Tracks human player tendencies for future political decisions
• Simulates realistic political behavior for different AI difficulty levels

#![allow(unused)]
fn main() {
#[derive(Resource)]
pub struct AIPoliticsConfig {
    /// AI personality profiles
    pub personalities: HashMap<Entity, AIPoliticalPersonality>,
    /// AI decision making parameters
    pub decision_weights: AIPoliticsWeights,
    /// Historic interaction with players
    pub player_interaction_history: HashMap<Entity, PlayerInteractionHistory>,
}

#[derive(Clone, Debug)]
pub struct AIPoliticalPersonality {
    /// How aggressive the AI is
    pub aggression: f32,
    /// How trustworthy the AI is
    pub trustworthiness: f32,
    /// How risk-averse the AI is
    pub risk_aversion: f32,
    /// How vengeful the AI is
    pub vengefulness: f32,
    /// How the AI evaluates deals
    pub deal_evaluation_strategy: DealEvaluationStrategy,
}

/// System for AI deal evaluation
pub fn ai_evaluate_deal(
    ai_politics_config: Res<AIPoliticsConfig>,
    threat_assessment: Res<ThreatAssessment>,
    board_state: Res<BoardState>,
    deal: &Deal,
    ai_player: Entity,
) -> DealEvaluationResult {
    if let Some(personality) = ai_politics_config.personalities.get(&ai_player) {
        // Get AI personality
        let trust_factor = personality.trustworthiness;
        let risk_factor = personality.risk_aversion;
        
        // Calculate deal value
        let mut deal_value = 0.0;
        
        for term in &deal.terms {
            match term {
                DealTerm::NonAggression { target, duration } => {
                    // Value based on target threat and duration
                    let target_threat = threat_assessment.player_threats
                        .get(target)
                        .map(|t| t.0)
                        .unwrap_or(0.0);
                    
                    deal_value += target_threat * (*duration as f32) * 0.5;
                },
                // Evaluate other term types...
                _ => {},
            }
        }
        
        // Adjust for proposer's trustworthiness
        let proposer_trust = ai_politics_config.player_interaction_history
            .get(&ai_player)
            .and_then(|h| h.player_trust.get(&deal.proposer))
            .copied()
            .unwrap_or(0.5);
        
        deal_value *= proposer_trust;
        
        // Make decision based on value
        if deal_value > personality.deal_threshold {
            DealEvaluationResult::Accept
        } else {
            DealEvaluationResult::Reject { reason: "Not valuable enough".to_string() }
        }
    } else {
        // Default rejection if no personality
        DealEvaluationResult::Reject { reason: "No AI personality configured".to_string() }
    }
}
}

UI Components

The multiplayer politics UI provides:

• Deal proposal interface with customizable terms
• Alliance status indicators
• Threat assessment visualization
• Communication tools with appropriate filters
• Deal history and player reputation tracking

#![allow(unused)]
fn main() {
#[derive(Component)]
pub struct PoliticsUIState {
    /// Currently selected player for political actions
    pub selected_player: Option<Entity>,
    /// Deal being constructed
    pub draft_deal: Option<DraftDeal>,
    /// UI mode
    pub ui_mode: PoliticsUIMode,
}

/// System for rendering politics UI
pub fn render_politics_ui(
    mut commands: Commands,
    mut egui_context: ResMut<EguiContext>,
    politics_ui_state: Res<PoliticsUIState>,
    politics_components: Query<&PoliticsComponent>,
    players: Query<(Entity, &PlayerName)>,
    threat_assessment: Res<ThreatAssessment>,
) {
    // Implementation of politics UI rendering...
}
}

Integration with Other Systems

The politics system integrates with several other game systems:

Combat System Integration

#![allow(unused)]
fn main() {
/// System for applying political factors to combat
pub fn apply_politics_to_combat(
    politics_components: Query<&PoliticsComponent>,
    mut attack_events: EventReader<DeclareAttackerEvent>,
    mut attack_modifiers: EventWriter<AttackModifierEvent>,
    alliances: Query<&Alliance>,
) {
    for event in attack_events.read() {
        if let Ok(attacker_politics) = politics_components.get(event.controller) {
            // Check for deals preventing attacks
            for deal in &attacker_politics.active_deals {
                for term in &deal.terms {
                    if let DealTerm::NonAggression { target, duration } = term {
                        if *target == event.defender && deal.status == DealStatus::Active {
                            // This attack would violate a non-aggression deal
                            attack_modifiers.send(AttackModifierEvent {
                                attacker: event.attacker,
                                defender: event.defender,
                                modification: AttackModification::PreventAttack {
                                    reason: "Non-aggression deal in effect".to_string(),
                                },
                            });
                        }
                    }
                }
            }
            
            // Check for alliances
            if let Some(alliance_strength) = attacker_politics.alliances.get(&event.defender) {
                // Alliance strength affects whether attack is allowed
                if *alliance_strength == AllianceStrength::Strong {
                    attack_modifiers.send(AttackModifierEvent {
                        attacker: event.attacker,
                        defender: event.defender,
                        modification: AttackModification::DissuadeAttack {
                            reason: "Strong alliance in effect".to_string(),
                            penalty: 2.0,
                        },
                    });
                }
            }
        }
    }
}
}

Card Effect Integration

#![allow(unused)]
fn main() {
/// System for applying political factors to targeted effects
pub fn apply_politics_to_targeting(
    politics_components: Query<&PoliticsComponent>,
    mut targeting_events: EventReader<TargetSelectionEvent>,
    mut targeting_modifiers: EventWriter<TargetingModifierEvent>,
) {
    for event in targeting_events.read() {
        if let Ok(caster_politics) = politics_components.get(event.controller) {
            // Check for deals affecting targeting
            for deal in &caster_politics.active_deals {
                for term in &deal.terms {
                    // Handle various deal terms affecting targeting
                    match term {
                        DealTerm::NoCounterspell { target, .. } => {
                            if *target == event.target_controller && 
                               is_counterspell(event.source) {
                                // This targeting would violate a no-counterspell deal
                                targeting_modifiers.send(TargetingModifierEvent {
                                    source: event.source,
                                    target: event.target,
                                    modification: TargetingModification::PreventTargeting {
                                        reason: "No-counterspell deal in effect".to_string(),
                                    },
                                });
                            }
                        },
                        // Handle other deal terms...
                        _ => {},
                    }
                }
            }
            
            // Check for alliances affecting targeting
            if let Some(alliance_strength) = caster_politics.alliances.get(&event.target_controller) {
                if is_negative_effect(event.source, event.target) {
                    match alliance_strength {
                        AllianceStrength::Strong => {
                            targeting_modifiers.send(TargetingModifierEvent {
                                source: event.source,
                                target: event.target,
                                modification: TargetingModification::DissuadeTargeting {
                                    reason: "Strong alliance in effect".to_string(),
                                    penalty: 3.0,
                                },
                            });
                        },
                        // Handle other alliance levels...
                        _ => {},
                    }
                }
            }
        }
    }
}
}

Constraints and Limitations

The politics system operates within these constraints:

• No rules enforcement of political agreements (maintaining game integrity)
• Appropriate limits on information sharing for hidden information
• Configurable table talk policies to match playgroup preferences
• Balance between automation and player agency in political decisions

Testing Politics Features

#![allow(unused)]
fn main() {
#[test]
fn test_deal_creation_and_acceptance() {
    let mut app = App::new();
    setup_test_game(&mut app);
    
    // Create players
    let player1 = app.world.spawn((
        Player,
        PlayerName("Player 1".to_string()),
        PoliticsComponent::default(),
    )).id();
    
    let player2 = app.world.spawn((
        Player,
        PlayerName("Player 2".to_string()),
        PoliticsComponent::default(),
    )).id();
    
    // Create a deal proposal
    let deal_terms = vec![
        DealTerm::NonAggression {
            target: player2,
            duration: 2,
        },
    ];
    
    app.world.send_event(DealProposalEvent {
        proposer: player1,
        targets: vec![player2],
        terms: deal_terms,
        expiration: Some(DealExpiration::Turns(2)),
        timestamp: 0.0,
    });
    
    app.update();
    
    // Check that deal was created
    let politics1 = app.world.get::<PoliticsComponent>(player1).unwrap();
    assert_eq!(politics1.active_deals.len(), 1);
    assert_eq!(politics1.active_deals[0].status, DealStatus::Proposed);
    
    // Accept the deal
    let deal_id = politics1.active_deals[0].id;
    app.world.send_event(DealResponseEvent {
        deal_id,
        response_type: DealResponseType::Accept,
        player: player2,
        timestamp: 1.0,
    });
    
    app.update();
    
    // Verify deal is now active
    let politics1_updated = app.world.get::<PoliticsComponent>(player1).unwrap();
    assert_eq!(politics1_updated.active_deals[0].status, DealStatus::Active);
    assert_eq!(politics1_updated.active_deals[0].acceptors, vec![player2]);
}

#[test]
fn test_goad_mechanics() {
    let mut app = App::new();
    setup_test_game(&mut app);
    
    // Create players
    let player1 = app.world.spawn(Player).id();
    let player2 = app.world.spawn(Player).id();
    
    // Create a creature
    let creature = app.world.spawn((
        CardName("Test Creature".to_string()),
        CardType::Creature,
        Power(3),
        Toughness(3),
        Controller(player1),
        OnBattlefield,
    )).id();
    
    // Goad the creature
    app.world.entity_mut(creature).insert(Goaded {
        goaded_by: player2,
        expires_at: ExpiryTiming::EndOfTurn,
    });
    
    // Set up combat phase
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::DeclareAttackers);
    app.world.resource_mut::<TurnManager>().active_player = player1;
    
    app.update();
    
    // Get attack requirements
    let attack_requirements = app.world.resource::<Events<AttackRequirementEvent>>()
        .get_reader()
        .read(&app.world.resource::<Events<AttackRequirementEvent>>())
        .collect::<Vec<_>>();
    
    // Verify goad requirements are enforced
    assert!(!attack_requirements.is_empty());
    assert_eq!(attack_requirements[0].creature, creature);
    assert!(attack_requirements[0].must_attack);
    assert_eq!(attack_requirements[0].cannot_attack, vec![player2]);
}
}

Related Resources

• Politics Testing: Details on testing political mechanics
• Commander-Specific Cards: Cards with political mechanics
• Multiplayer Combat: How combat works in multiplayer
• Goad Implementation: More details on goad effects

Politics System Testing

Overview

This document outlines the testing approach for the Multiplayer Politics system within the Commander game engine. Due to the complex nature of political interactions and their impact on game state, thorough testing is essential to ensure correct behavior and integration with other components.

Test Categories

The Politics system testing is organized into several key categories:

1. Unit Tests

Unit tests focus on isolated functionality of the Politics system components:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_monarch_transitions() {
        // Test monarch assignment and transitions
    }
    
    #[test]
    fn test_vote_tallying() {
        // Test vote counting and resolution
    }
    
    #[test]
    fn test_deal_validation() {
        // Test deal validation logic
    }
    
    #[test]
    fn test_alliance_formation() {
        // Test alliance creation and tracking
    }
    
    #[test]
    fn test_goad_effects() {
        // Test goad mechanics and expiration
    }
}
}

2. Integration Tests

Integration tests verify Politics system interactions with other game systems:

• Combat integration (goad effects, alliance-based combat restrictions)
• Turn structure integration (monarch draw effects, deal expiration)
• Card effects that interact with political mechanics
• UI feedback for political events
• Threat assessment impact on AI decision making

3. End-to-End Tests

End-to-end tests simulate full game scenarios involving political elements:

• Four-player game with complex political interactions
• AI decision-making in political contexts
• Network synchronization of political state
• Full game simulations with political mechanics enabled

Testing The Monarch Mechanic

The Monarch mechanic requires specific test cases:

1. Monarch Assignment

   • Test initial monarch assignment
   • Test monarch transfer through card effects
   • Test monarch transfer through combat damage

2. Monarch Effects

   • Verify correct card draw during end step
   • Test interaction with replacement effects
   • Validate monarch status persistence across turns

3. Edge Cases

   • Test monarch behavior when player loses/leaves game
   • Test simultaneous monarch-granting effects
   • Test prevention of monarch transfer

#![allow(unused)]
fn main() {
#[test]
fn test_monarch_combat_transfer() {
    let mut app = App::new();
    setup_test_game(&mut app);
    
    // Create players
    let player1 = app.world.spawn(Player).id();
    let player2 = app.world.spawn(Player).id();
    
    // Set initial monarch
    let mut monarch_state = MonarchState {
        current_monarch: Some(player1),
        last_changed: Some(0.0),
    };
    app.insert_resource(monarch_state);
    
    // Player entity should have Monarch component
    app.world.entity_mut(player1).insert(Monarch);
    
    // Create attacking creature
    let creature = app.world.spawn((
        CardName("Test Creature".to_string()),
        CardType::Creature,
        Power(3),
        Toughness(3),
        Controller(player2),
        OnBattlefield,
    )).id();
    
    // Send combat damage event
    app.world.send_event(CombatDamageEvent {
        source: creature,
        target: player1,
        amount: 3,
        is_commander_damage: false,
        attacking_player_controller: player2,
        defending_player: player1,
    });
    
    app.update();
    
    // Verify monarch transferred
    let updated_monarch = app.world.resource::<MonarchState>();
    assert_eq!(updated_monarch.current_monarch, Some(player2));
    assert!(app.world.entity(player2).contains::<Monarch>());
    assert!(!app.world.entity(player1).contains::<Monarch>());
}
}

Testing The Voting System

The voting system tests include:

1. Vote Initialization

   • Test vote creation and option definition
   • Validate vote accessibility to all players
   • Test timing restrictions on votes

2. Vote Casting

   • Test basic vote casting mechanics
   • Test vote weight modifiers (e.g., extra votes from effects)
   • Validate vote time limits
   • Test voting for multiple options (Council's Dilemma)

3. Vote Resolution

   • Test tie-breaking logic
   • Verify correct application of voting results
   • Test effects that modify vote outcomes
   • Test scaling effects based on vote counts

#![allow(unused)]
fn main() {
#[test]
fn test_voting_resolution() {
    let mut app = App::new();
    setup_test_game(&mut app);
    
    // Create players
    let player1 = app.world.spawn(Player).id();
    let player2 = app.world.spawn(Player).id();
    let player3 = app.world.spawn(Player).id();
    
    // Create voting card
    let voting_card = app.world.spawn((
        CardName("Council's Judgment".to_string()),
        VotingMechanic {
            voting_type: VotingType::WillOfCouncil,
            options: vec!["Option A".to_string(), "Option B".to_string()],
            resolution: VoteResolutionMethod::MostVotes,
        },
        Controller(player1),
    )).id();
    
    // Cast votes
    let votes = HashMap::from([
        (player1, "Option A".to_string()),
        (player2, "Option B".to_string()),
        (player3, "Option A".to_string()),
    ]);
    
    // Send vote completion event
    app.world.send_event(VoteCompletionEvent {
        source_card: voting_card,
        votes,
        timestamp: 1.0,
    });
    
    app.update();
    
    // Verify correct effect was applied for winning option "Option A"
    // Further assertions based on the expected outcome
}
}

Testing The Deal System

The deal system requires comprehensive testing:

1. Deal Creation

   • Test deal proposal structure
   • Validate term specification
   • Test duration settings
   • Test deal limits per player

2. Deal Negotiation

   • Test acceptance/rejection mechanics
   • Test counter-proposal handling
   • Validate notification system
   • Test multi-player deals

3. Deal Enforcement

   • Test automatic deal monitoring
   • Validate deal violation detection
   • Test consequences application
   • Test enforcement of complex terms

4. Deal History

   • Test deal history tracking
   • Validate reputation system updates
   • Test history influence on AI decisions
   • Test broken deal statistics

#![allow(unused)]
fn main() {
#[test]
fn test_deal_lifecycle() {
    let mut app = App::new();
    setup_test_game(&mut app);
    
    // Create players with politics components
    let player1 = app.world.spawn((
        Player,
        PlayerName("Player 1".to_string()),
        PoliticsComponent::default(),
    )).id();
    
    let player2 = app.world.spawn((
        Player,
        PlayerName("Player 2".to_string()),
        PoliticsComponent::default(),
    )).id();
    
    // Create a deal proposal
    let deal_terms = vec![
        DealTerm::NonAggression {
            target: player2,
            duration: 2,
        },
    ];
    
    app.world.send_event(DealProposalEvent {
        proposer: player1,
        targets: vec![player2],
        terms: deal_terms,
        expiration: Some(DealExpiration::Turns(2)),
        timestamp: 0.0,
    });
    
    app.update();
    
    // Verify deal proposal created
    let politics1 = app.world.get::<PoliticsComponent>(player1).unwrap();
    assert_eq!(politics1.active_deals.len(), 1);
    assert_eq!(politics1.active_deals[0].status, DealStatus::Proposed);
    
    // Accept the deal
    let deal_id = politics1.active_deals[0].id;
    app.world.send_event(DealResponseEvent {
        deal_id,
        response_type: DealResponseType::Accept,
        player: player2,
        timestamp: 1.0,
    });
    
    app.update();
    
    // Verify deal is now active
    let politics1_updated = app.world.get::<PoliticsComponent>(player1).unwrap();
    assert_eq!(politics1_updated.active_deals[0].status, DealStatus::Active);
    
    // Test deal expiration
    advance_game_turns(&mut app, 2);
    app.update();
    
    // Verify deal has expired
    let politics1_final = app.world.get::<PoliticsComponent>(player1).unwrap();
    assert_eq!(politics1_final.active_deals[0].status, DealStatus::Expired);
}
}

Testing Alliance Mechanics

The alliance system requires specific test cases:

1. Alliance Formation

   • Test alliance creation
   • Test alliance strength levels
   • Validate multi-player alliance formation

2. Alliance Effects

   • Test combat restrictions based on alliances
   • Test targeting restrictions for allied players
   • Validate benefits between allied players

3. Alliance Dissolution

   • Test voluntary alliance breaking
   • Test automatic alliance expiration
   • Validate alliance history tracking

#![allow(unused)]
fn main() {
#[test]
fn test_alliance_combat_restrictions() {
    let mut app = App::new();
    setup_test_game(&mut app);
    
    // Create players
    let player1 = app.world.spawn((
        Player,
        PoliticsComponent::default(),
    )).id();
    
    let player2 = app.world.spawn((
        Player,
        PoliticsComponent::default(),
    )).id();
    
    // Create strong alliance
    let mut politics1 = app.world.get_mut::<PoliticsComponent>(player1).unwrap();
    politics1.alliances.insert(player2, AllianceStrength::Strong);
    
    // Create creature
    let creature = app.world.spawn((
        CardType::Creature,
        Controller(player1),
        OnBattlefield,
    )).id();
    
    // Attempt to attack allied player
    app.world.send_event(DeclareAttackerEvent {
        attacker: creature,
        defender: player2,
        controller: player1,
    });
    
    app.update();
    
    // Check for attack modification event
    let attack_mods = app.world.resource::<Events<AttackModifierEvent>>()
        .get_reader()
        .read(&app.world.resource::<Events<AttackModifierEvent>>())
        .collect::<Vec<_>>();
    
    assert!(!attack_mods.is_empty());
    assert_eq!(attack_mods[0].attacker, creature);
    assert_eq!(attack_mods[0].defender, player2);
    
    // Verify correct modification type (should be DissuadeAttack for strong alliance)
    match &attack_mods[0].modification {
        AttackModification::DissuadeAttack { reason, penalty } => {
            assert!(reason.contains("alliance"));
            assert!(*penalty > 0.0);
        },
        _ => panic!("Expected DissuadeAttack modification"),
    }
}
}

Testing Goad Mechanics

Goad mechanics require specific testing:

1. Goad Application

   • Test applying goad to creatures
   • Test goad duration tracking
   • Test multiple simultaneous goad effects

2. Goad Attack Requirements

   • Test forced attack requirement
   • Test restriction on attacking goader
   • Validate legal target determination

3. Goad Edge Cases

   • Test goad with no legal attack targets
   • Test goad when creature cannot attack
   • Test interaction with other attack restrictions

#![allow(unused)]
fn main() {
#[test]
fn test_goad_mechanics() {
    let mut app = App::new();
    setup_test_game(&mut app);
    
    // Create 3 players
    let player1 = app.world.spawn(Player).id();
    let player2 = app.world.spawn(Player).id();
    let player3 = app.world.spawn(Player).id();
    
    // Create a creature
    let creature = app.world.spawn((
        CardName("Test Creature".to_string()),
        CardType::Creature,
        Power(3),
        Toughness(3),
        Controller(player1),
        OnBattlefield,
        CanAttack(true),
    )).id();
    
    // Goad the creature
    app.world.entity_mut(creature).insert(Goaded {
        goaded_by: player2,
        expires_at: ExpiryTiming::EndOfTurn,
    });
    
    // Set up combat phase
    app.world.resource_mut::<TurnManager>().current_phase = Phase::Combat(CombatStep::DeclareAttackers);
    app.world.resource_mut::<TurnManager>().active_player = player1;
    
    app.update();
    
    // Get attack requirements
    let attack_requirements = app.world.resource::<Events<AttackRequirementEvent>>()
        .get_reader()
        .read(&app.world.resource::<Events<AttackRequirementEvent>>())
        .collect::<Vec<_>>();
    
    // Verify goad requirements are enforced
    assert!(!attack_requirements.is_empty());
    assert_eq!(attack_requirements[0].creature, creature);
    assert!(attack_requirements[0].must_attack);
    assert_eq!(attack_requirements[0].cannot_attack, vec![player2]);
    
    // Advance turn to test goad expiration
    advance_turn(&mut app);
    
    // Verify goad has expired
    assert!(!app.world.entity(creature).contains::<Goaded>());
}
}

Testing Threat Assessment

The threat assessment system requires verification:

1. Threat Calculation

   • Test basic threat score calculation
   • Test contribution of different threat factors
   • Validate dynamic threat updates

2. Threat Visualization

   • Test threat UI display
   • Test threat history tracking
   • Validate threat factor breakdown

3. AI Integration

   • Test AI use of threat assessment
   • Validate threat-based targeting
   • Test strategic adjustments based on threat

#![allow(unused)]
fn main() {
#[test]
fn test_threat_assessment() {
    let mut app = App::new();
    setup_test_game(&mut app);
    
    // Create players
    let player1 = app.world.spawn(Player).id();
    let player2 = app.world.spawn(Player).id();
    
    // Initialize threat assessment
    app.insert_resource(ThreatAssessment {
        player_threats: HashMap::new(),
        threat_factors: HashMap::new(),
        threat_history: HashMap::new(),
    });
    
    // Create board state for player1
    for _ in 0..5 {
        app.world.spawn((
            CardType::Creature,
            Controller(player1),
            OnBattlefield,
        ));
    }
    
    // Create commander for player1
    app.world.spawn((
        CardType::Creature,
        Commander,
        Controller(player1),
        OnBattlefield,
    ));
    
    // Create smaller board for player2
    for _ in 0..2 {
        app.world.spawn((
            CardType::Creature,
            Controller(player2),
            OnBattlefield,
        ));
    }
    
    // Run threat assessment system
    app.add_systems(Update, update_threat_assessment);
    app.update();
    
    // Check threat levels
    let threat = app.world.resource::<ThreatAssessment>();
    
    // Player1 should have higher threat than player2
    let player1_threat = threat.player_threats.get(&player1).unwrap();
    let player2_threat = threat.player_threats.get(&player2).unwrap();
    
    assert!(player1_threat.0 > player2_threat.0);
    
    // Verify threat factors were recorded
    assert!(!threat.threat_factors.get(&player1).unwrap().is_empty());
    
    // Check commander presence factor
    let commander_factor = threat.threat_factors.get(&player1).unwrap()
        .iter()
        .find(|f| matches!(f.factor_type, ThreatFactorType::CommanderPresence));
    
    assert!(commander_factor.is_some());
}
}

Mock Testing Approaches

For complex political scenarios, mock testing is employed:

#![allow(unused)]
fn main() {
#[test]
fn test_complex_political_scenario() {
    let mut app = App::new();
    
    // Setup test environment
    app.add_plugins(MinimalPlugins)
       .add_plugin(PoliticsPlugin)
       .add_systems(Startup, setup_test_scenario);
       
    // Mock player actions
    let players = setup_four_player_game(&mut app);
    
    // Simulate complex political scenario
    simulate_monarchy_contest(&mut app, &players);
    simulate_deal_making(&mut app, &players);
    simulate_voting_session(&mut app, &players);
    simulate_alliance_formation(&mut app, &players);
    simulate_threat_based_targeting(&mut app, &players);
    
    // Verify expected outcomes
    verify_political_state(&app, &expected_state);
}
}

Property-Based Testing

For robust validation of political mechanics, property-based testing is used:

#![allow(unused)]
fn main() {
#[test]
fn test_voting_properties() {
    // Property: All votes must be counted
    proptest!(|(votes: Vec<(Entity, VoteChoice)>)| {
        let result = tally_votes(&votes);
        assert_eq!(result.total_votes, votes.len());
    });
    
    // Property: Winning option must have most votes
    proptest!(|(votes: Vec<(Entity, VoteChoice)>)| {
        let result = tally_votes(&votes);
        // Verify winning option has highest count
    });
    
    // Property: Goad must always allow at least one legal attack target
    proptest!(|(players: Vec<Entity>, goaded_by: Entity)| {
        let legal_targets = determine_legal_attack_targets(players.clone(), goaded_by);
        // Verify at least one legal target if there are enough players
        if players.len() > 2 {
            assert!(!legal_targets.is_empty());
        }
    });
}
}

Network Testing

Political systems must be tested for correct network behavior:

1. State Synchronization

   • Test monarch status synchronization
   • Validate vote transmission and collection
   • Test deal state synchronization
   • Test alliance state replication

2. Latency Handling

   • Test delayed political decisions
   • Validate timeout handling for votes/deals
   • Test recovery from connection issues

3. Conflict Resolution

   • Test resolution of conflicting political actions
   • Validate deterministic outcomes across peers

Regression Test Suite

The Politics system maintains a regression test suite covering:

1. Known past issues and their fixes
2. Edge cases discovered during development
3. Community-reported political interaction bugs

Performance Testing

Political mechanics are tested for performance impacts:

1. Scaling Tests

   • Performance with many simultaneous deals
   • Vote tallying with large player counts
   • Political state update propagation
   • Threat assessment with complex board states

2. Memory Usage

   • Test memory footprint of complex political states
   • Validate cleanup of expired political objects

Test Fixtures

Reusable test fixtures include:

• Standard 4-player table setup
• Pre-defined political scenarios
• Mock AI political personalities
• Reference deal/vote templates
• Standard threat assessment profiles

Continuous Integration

Politics tests are integrated into CI with:

• Automated test runs on PR submission
• Coverage reports for political mechanics
• Performance comparison against baseline
• Parallel testing of different political scenarios

Related Resources

• Multiplayer Politics - Core politics system documentation
• Politics Tests - Specific test case implementations
• Commander-Specific Cards - Cards with political mechanics

Partner Commanders

This document details the implementation of partner commanders and related mechanics in the Commander format.

Overview

Partner is a mechanic introduced in Commander 2016 that allows a deck to have two commanders instead of one. There are several variations of the partner mechanic:

1. Traditional Partners: Cards with the text "Partner" can pair with any other card that has Partner
2. Partner With: Cards with "Partner with [specific card]" can only pair with that specific card
3. Background: A commander that can have a Background enchantment as a second commander
4. Friends Forever: Cards with "Friends Forever" can pair with any other card that has Friends Forever

Rules Implementation

Core Partner Rules

The partner mechanic modifies several fundamental Commander rules:

1. Two commanders instead of one
2. Color identity is the combined colors of both commanders
3. Starting life total and commander damage tracking apply to each commander separately
4. Both commanders start in the command zone
5. Commander tax applies to each commander separately

Implementation Details

#![allow(unused)]
fn main() {
/// Component marking an entity as a partner commander
#[derive(Component, Clone, Debug)]
pub enum PartnerType {
    /// Can partner with any other commander with Partner
    Universal,
    /// Can only partner with a specific commander
    Specific(Entity),
    /// Can have a Background as a partner
    CanHaveBackground,
    /// Is a Background enchantment
    IsBackground,
    /// Can partner with any Friends Forever commander
    FriendsForever,
}

/// Resource tracking partner commanders
#[derive(Resource)]
pub struct PartnerSystem {
    /// Maps players to their partner commanders
    pub player_partners: HashMap<Entity, Vec<Entity>>,
    /// Tracks which commanders are partnered together
    pub partnered_with: HashMap<Entity, Entity>,
}

/// System to validate partner legality during deck construction
pub fn validate_partner_legality(
    player: Entity,
    deck: &Deck,
    partners: &Query<(Entity, &CardName, &PartnerType)>,
) -> Result<(), DeckValidationError> {
    // Get commanders marked as partners
    let commander_entities = deck.get_commanders();
    
    // Filter to keep only entities with Partner component
    let partner_entities: Vec<Entity> = partners
        .iter_many(commander_entities)
        .map(|(entity, _, _)| entity)
        .collect();
    
    // Validate partner relationships
    match partner_entities.len() {
        0 => Ok(()), // No partners, standard single commander
        1 => Err(DeckValidationError::SinglePartnerNotAllowed), // Single partner needs a pair
        2 => validate_two_partners(&partner_entities, partners), // Check if these two can partner
        _ => Err(DeckValidationError::TooManyPartners), // More than 2 partners not allowed
    }
}

/// Validates if two commanders can be partners
fn validate_two_partners(
    entities: &[Entity],
    partners: &Query<(Entity, &CardName, &PartnerType)>,
) -> Result<(), DeckValidationError> {
    let (entity_a, name_a, type_a) = partners.get(entities[0]).unwrap();
    let (entity_b, name_b, type_b) = partners.get(entities[1]).unwrap();
    
    match (type_a, type_b) {
        // Universal partners can pair with any other universal partner
        (PartnerType::Universal, PartnerType::Universal) => Ok(()),
        
        // Specific partners can only pair with their named partner
        (PartnerType::Specific(target), _) if *target == entity_b => Ok(()),
        (_, PartnerType::Specific(target)) if *target == entity_a => Ok(()),
        
        // Background pairings
        (PartnerType::CanHaveBackground, PartnerType::IsBackground) => Ok(()),
        (PartnerType::IsBackground, PartnerType::CanHaveBackground) => Ok(()),
        
        // Friends Forever pairings
        (PartnerType::FriendsForever, PartnerType::FriendsForever) => Ok(()),
        
        // All other combinations are invalid
        _ => Err(DeckValidationError::InvalidPartnerCombination {
            commander_a: name_a.0.clone(),
            commander_b: name_b.0.clone(),
        }),
    }
}
}

Color Identity with Partners

A deck with partner commanders uses the combined color identity of both commanders:

#![allow(unused)]
fn main() {
/// Calculate color identity for a deck with partners
pub fn calculate_partner_color_identity(
    commanders: &[Entity],
    identity_query: &Query<&ColorIdentity>,
) -> ColorIdentity {
    let mut combined_identity = ColorIdentity::default();
    
    for commander in commanders {
        if let Ok(identity) = identity_query.get(*commander) {
            combined_identity = combined_identity.union(identity);
        }
    }
    
    combined_identity
}
}

Partner Variations

Partner With

The "Partner with" mechanic has additional functionality beyond allowing two commanders:

1. When either commander enters the battlefield, its controller may search their library for the other
2. This tutor effect requires special implementation

#![allow(unused)]
fn main() {
/// Component for the "Partner with" tutoring ability
#[derive(Component)]
pub struct PartnerWithTutorAbility {
    pub partner_name: String,
}

/// System that handles the "Partner with" tutoring ability
pub fn handle_partner_with_tutor(
    mut commands: Commands,
    mut entered_battlefield: EventReader<EnteredBattlefieldEvent>,
    tutor_abilities: Query<(&PartnerWithTutorAbility, &Owner)>,
    mut tutor_events: EventWriter<TutorEvent>,
) {
    for event in entered_battlefield.read() {
        if let Ok((ability, owner)) in tutor_abilities.get(event.entity) {
            // Create a tutor effect allowing player to search for the partner
            tutor_events.send(TutorEvent {
                player: owner.0,
                card_name: ability.partner_name.clone(),
                origin: event.entity,
                destination: Zone::Hand,
                optional: true,
            });
        }
    }
}
}

Background

The Background mechanic, introduced in Commander Legends: Battle for Baldur's Gate, allows certain commanders to have a Background enchantment as their second commander:

#![allow(unused)]
fn main() {
/// Component marking a card as a Background
#[derive(Component)]
pub struct Background;

/// Component for commanders that can have a Background
#[derive(Component)]
pub struct CanHaveBackground;

/// System to validate Background legality
pub fn validate_background_legality(
    commanders: &[Entity],
    can_have_query: &Query<Entity, With<CanHaveBackground>>,
    background_query: &Query<Entity, With<Background>>,
) -> Result<(), DeckValidationError> {
    if commanders.len() != 2 {
        return Ok(());
    }
    
    let has_commander_with_background = can_have_query
        .iter_many(commanders)
        .count() == 1;
        
    let has_background = background_query
        .iter_many(commanders)
        .count() == 1;
    
    if has_commander_with_background && has_background {
        Ok(())
    } else if has_commander_with_background || has_background {
        Err(DeckValidationError::IncompleteBackgroundPairing)
    } else {
        Ok(()) // Not using Background mechanic
    }
}
}

User Interface Considerations

The UI needs special handling for partner commanders:

1. Both commanders need to be displayed in the command zone
2. Players need a way to choose which commander to cast
3. Commander tax display needs to track each commander separately

Testing Partner Mechanics

#![allow(unused)]
fn main() {
#[test]
fn test_universal_partners() {
    let mut app = App::new();
    app.add_systems(Startup, setup_test_partners);
    app.add_systems(Update, validate_partner_legality);
    
    // Test universal partners (e.g., Thrasios and Tymna)
    let thrasios = app.world.spawn((
        CardName("Thrasios, Triton Hero".to_string()),
        PartnerType::Universal,
    )).id();
    
    let tymna = app.world.spawn((
        CardName("Tymna the Weaver".to_string()),
        PartnerType::Universal,
    )).id();
    
    let deck = create_test_deck(vec![thrasios, tymna]);
    let result = validate_deck(&app.world, deck);
    assert!(result.is_ok());
}

#[test]
fn test_partners_with() {
    // Test for "Partner with" mechanic (e.g., Brallin and Shabraz)
    // Implementation details...
}

#[test]
fn test_background() {
    // Test for Background mechanic
    // Implementation details...
}
}

Related Documentation

• Commander Damage: How commander damage is tracked with partner commanders
• Command Zone: How partners behave in the command zone
• Commander Tax: How tax is applied to each partner
• Color Identity: How color identity is calculated with partners

Commander Ninjutsu

This document details the implementation of the Commander Ninjutsu mechanic in the Commander format.

Overview

Commander Ninjutsu is a Commander-specific variant of the Ninjutsu mechanic, introduced on the card "Yuriko, the Tiger's Shadow" from Commander 2018. It allows a commander with this ability to be put onto the battlefield from the command zone, bypassing commander tax.

Mechanic Definition

Commander Ninjutsu {Cost} — {Cost}, Return an unblocked attacker you control to hand: Put this card from the command zone onto the battlefield tapped and attacking.

Key differences from regular Ninjutsu:

1. It can be activated from the command zone (instead of only from hand)
2. It bypasses the need to cast the commander, avoiding commander tax
3. It allows the commander to enter the battlefield directly attacking

Rules Implementation

Core Commander Ninjutsu Rules

#![allow(unused)]
fn main() {
/// Component for cards with Commander Ninjutsu
#[derive(Component, Clone, Debug)]
pub struct CommanderNinjutsu {
    /// Mana cost to activate the ability
    pub cost: ManaCost,
}

/// Event triggered when a Commander Ninjutsu ability is activated
#[derive(Event)]
pub struct CommanderNinjutsuEvent {
    /// The commander with ninjutsu being put onto the battlefield
    pub commander: Entity,
    /// The creature being returned to hand
    pub returned_creature: Entity,
    /// The player being attacked
    pub defending_player: Entity,
    /// The player activating the ability
    pub controller: Entity,
}

/// System that handles Commander Ninjutsu activation
pub fn handle_commander_ninjutsu(
    mut commands: Commands,
    mut ninjutsu_events: EventReader<CommanderNinjutsuEvent>,
    mut zone_transitions: EventWriter<ZoneTransitionEvent>,
    mut attacking_status: EventWriter<SetAttackingEvent>,
    command_zone: Query<&CommandZone>,
) {
    for event in ninjutsu_events.read() {
        // Verify commander is in command zone
        if !is_in_command_zone(event.commander, &command_zone) {
            continue;
        }
        
        // 1. Return the unblocked attacker to hand
        zone_transitions.send(ZoneTransitionEvent {
            entity: event.returned_creature,
            from: Zone::Battlefield,
            to: Zone::Hand,
            cause: TransitionCause::Ability {
                source: event.commander,
                ability_name: "Commander Ninjutsu".to_string(),
            },
        });
        
        // 2. Put commander onto battlefield
        zone_transitions.send(ZoneTransitionEvent {
            entity: event.commander,
            from: Zone::Command,
            to: Zone::Battlefield,
            cause: TransitionCause::Ability {
                source: event.commander,
                ability_name: "Commander Ninjutsu".to_string(),
            },
        });
        
        // 3. Set commander as tapped and attacking
        commands.entity(event.commander).insert(Tapped);
        
        attacking_status.send(SetAttackingEvent {
            attacker: event.commander,
            defending_player: event.defending_player,
        });
    }
}
}

Activation Requirements

Commander Ninjutsu can only be activated during specific game states:

#![allow(unused)]
fn main() {
/// System to determine when Commander Ninjutsu can be activated
pub fn can_activate_commander_ninjutsu(
    commander: Entity,
    controller: Entity,
    game_state: &GameState,
    command_zone: &Query<&CommandZone>,
    ninjutsu_abilities: &Query<&CommanderNinjutsu>,
    attacking_creatures: &Query<(Entity, &AttackingStatus, &Controller)>,
) -> bool {
    // 1. Must be in the combat phase, after blockers are declared
    if !matches!(game_state.current_phase, 
                Phase::Combat(CombatStep::DeclareBlockers | 
                               CombatStep::CombatDamage)) {
        return false;
    }
    
    // 2. Commander must be in command zone
    if !is_in_command_zone(commander, command_zone) {
        return false;
    }
    
    // 3. Must have Commander Ninjutsu ability
    if !ninjutsu_abilities.contains(commander) {
        return false;
    }
    
    // 4. Must have an unblocked attacker to return to hand
    let has_unblocked_attacker = attacking_creatures
        .iter()
        .any(|(entity, status, creature_controller)| {
            creature_controller.0 == controller && 
            status.is_unblocked()
        });
    
    has_unblocked_attacker
}
}

Mana Cost and Commander Tax

The Commander Ninjutsu ability itself has a fixed cost that does not increase when the commander is put into the command zone:

#![allow(unused)]
fn main() {
/// Function to get the mana cost for activating Commander Ninjutsu
pub fn get_commander_ninjutsu_cost(
    commander: Entity,
    ninjutsu_abilities: &Query<&CommanderNinjutsu>,
) -> ManaCost {
    // Commander Ninjutsu cost is fixed and doesn't include commander tax
    if let Ok(ninjutsu) = ninjutsu_abilities.get(commander) {
        ninjutsu.cost.clone()
    } else {
        ManaCost::default() // Fallback, shouldn't happen
    }
}
}

However, the normal casting cost of the commander still increases each time the commander is put into the command zone from anywhere:

#![allow(unused)]
fn main() {
/// System that tracks commander movement to command zone to apply tax
pub fn track_commander_tax(
    mut tax_events: EventWriter<IncrementCommanderTaxEvent>,
    mut zone_transition_events: EventReader<ZoneTransitionEvent>,
    commander_query: Query<&Commander>,
) {
    for event in zone_transition_events.read() {
        if event.to == Zone::Command && commander_query.contains(event.entity) {
            // Increment commander tax, even for commanders with Ninjutsu
            tax_events.send(IncrementCommanderTaxEvent {
                commander: event.entity,
            });
        }
    }
}
}

User Interface Considerations

The UI needs special handling for Commander Ninjutsu:

1. Ability must be presented as an option during combat after blockers are declared
2. UI must show which unblocked attackers can be returned to hand
3. Cost display should show the fixed Ninjutsu cost (not affected by commander tax)

#![allow(unused)]
fn main() {
/// Function to get available Commander Ninjutsu actions
pub fn get_commander_ninjutsu_actions(
    player: Entity,
    game_state: &GameState,
    commanders: &Query<(Entity, &Commander, &CommanderNinjutsu, &Owner)>,
    unblocked_attackers: &Query<(Entity, &AttackingStatus, &Controller)>,
) -> Vec<CommanderNinjutsuAction> {
    let mut actions = Vec::new();
    
    // Only check during appropriate combat steps
    if !matches!(game_state.current_phase, 
                Phase::Combat(CombatStep::DeclareBlockers | 
                              CombatStep::CombatDamage)) {
        return actions;
    }
    
    // Get all unblocked attackers controlled by player
    let available_attackers: Vec<Entity> = unblocked_attackers
        .iter()
        .filter(|(_, status, controller)| {
            controller.0 == player && status.is_unblocked()
        })
        .map(|(entity, _, _)| entity)
        .collect();
    
    if available_attackers.is_empty() {
        return actions;
    }
    
    // Find commanders with ninjutsu in command zone
    for (commander, _, ninjutsu, owner) in commanders.iter() {
        if owner.0 == player && is_in_command_zone(commander, &game_state.zones) {
            // For each available attacker, create a potential action
            for attacker in &available_attackers {
                actions.push(CommanderNinjutsuAction {
                    commander,
                    unblocked_attacker: *attacker,
                    defending_player: get_defending_player(*attacker, &game_state),
                    cost: ninjutsu.cost.clone(),
                });
            }
        }
    }
    
    actions
}
}

Notable Cards with Commander Ninjutsu

Currently, only one card has Commander Ninjutsu:

• Yuriko, the Tiger's Shadow (Commander 2018)
  • Commander Ninjutsu {1}{U}{B}
  • Whenever Yuriko deals combat damage to a player, reveal the top card of your library and put it into your hand. You lose life equal to that card's mana value.
  • Partner With: None
  • Color Identity: Blue-Black

Implementation of Yuriko:

#![allow(unused)]
fn main() {
pub fn create_yuriko() -> impl Bundle {
    (
        CardName("Yuriko, the Tiger's Shadow".to_string()),
        CardType::Creature,
        CreatureType(vec!["Human".to_string(), "Ninja".to_string()]),
        Commander,
        Power(1),
        Toughness(3),
        ManaCost::parse("{1}{U}{B}"),
        ColorIdentity::parse("{U}{B}"),
        CommanderNinjutsu {
            cost: ManaCost::parse("{1}{U}{B}"),
        },
        CombatDamageTriggeredAbility {
            trigger_condition: CombatDamageCondition::DamageToPlayer,
            ability: Box::new(YurikoRevealEffect),
        },
    )
}
}

Testing Commander Ninjutsu

#![allow(unused)]
fn main() {
#[test]
fn test_commander_ninjutsu_activation() {
    let mut app = App::new();
    app.add_systems(Startup, setup_combat_test);
    app.add_systems(Update, (
        handle_commander_ninjutsu,
        track_commander_tax,
    ));
    
    // Create test entities
    let player = app.world.spawn_empty().id();
    let opponent = app.world.spawn_empty().id();
    
    // Create Yuriko commander in command zone
    let yuriko = app.world.spawn((
        CardName("Yuriko, the Tiger's Shadow".to_string()),
        Commander,
        CommanderNinjutsu { cost: ManaCost::parse("{1}{U}{B}") },
        Owner(player),
    )).id();
    
    // Add to command zone
    app.world.resource_mut::<Zones>().command.insert(yuriko);
    
    // Create an unblocked attacker
    let attacker = app.world.spawn((
        CardName("Ninja of the Deep Hours".to_string()),
        Controller(player),
        AttackingStatus {
            attacking: true,
            blocked: false,
            defending_player: Some(opponent),
        },
    )).id();
    
    // Set game state to post-blockers
    app.world.resource_mut::<GameState>().current_phase = Phase::Combat(CombatStep::DeclareBlockers);
    
    // Activate commander ninjutsu
    app.world.send_event(CommanderNinjutsuEvent {
        commander: yuriko,
        returned_creature: attacker,
        defending_player: opponent,
        controller: player,
    });
    
    app.update();
    
    // Verify Yuriko is now on battlefield and attacking
    let zones = app.world.resource::<Zones>();
    assert!(!zones.command.contains(&yuriko));
    assert!(zones.battlefield.contains(&yuriko));
    
    let attacking_status = app.world.get::<AttackingStatus>(yuriko).unwrap();
    assert!(attacking_status.attacking);
    assert_eq!(attacking_status.defending_player, Some(opponent));
    
    // Verify the attacker was returned to hand
    assert!(zones.hand.contains(&attacker));
}
}

Related Documentation

• Command Zone: How commanders move to and from the command zone
• Commander Tax: How tax is applied to commanders
• Combat: Combat phase implementation where Ninjutsu is activated

Commander Death Triggers

This document details the implementation of Commander death triggers and related mechanics in the Commander format.

Overview

In Commander, when a commander changes zones from the battlefield to any zone other than the command zone, the commander's owner has the option to move it to the command zone instead. This rule creates a special interaction with "dies" triggers, as the commander technically doesn't die (go to the graveyard) if moved to the command zone.

Rules Evolution

The Commander rules regarding death triggers have evolved over time:

1. Pre-2020 Rule: Commanders changing zones would create a replacement effect, preventing them from ever entering the graveyard.
2. Post-2020 Rule: Commanders now briefly touch the destination zone before being moved to the command zone as a state-based action, enabling death triggers to work.

Current Rule Implementation

Under the current rules, when a commander would leave the battlefield:

1. The commander actually moves to the destination zone (e.g., graveyard)
2. This movement triggers any applicable abilities (e.g., "when this creature dies")
3. The next time state-based actions are checked, the commander's owner may choose to move it to the command zone

This creates a brief window where the commander exists in the destination zone, allowing "dies" and other zone-change triggers to function normally.

Rules Implementation

Step 1: Zone Transition Tracking

#![allow(unused)]
fn main() {
/// System to handle initial zone transitions of commanders
pub fn track_commander_zone_transitions(
    mut zone_events: EventReader<ZoneTransitionEvent>,
    mut pending_commander_moves: ResMut<PendingCommanderMoves>,
    commander_query: Query<&Commander>,
) {
    for event in zone_events.read() {
        // Only care about commanders moving from battlefield
        if event.from == Zone::Battlefield && 
           event.to != Zone::Command && 
           commander_query.contains(event.entity) {
            
            // Record that this commander might move to command zone
            pending_commander_moves.commanders.insert(
                event.entity,
                CommanderMoveInfo {
                    current_zone: event.to,
                    last_transition_time: Instant::now(),
                }
            );
        }
    }
}
}

Step 2: State-Based Action for Command Zone Option

#![allow(unused)]
fn main() {
/// State-based action system that offers command zone option
pub fn commander_zone_choice_sba(
    mut commands: Commands,
    mut pending_moves: ResMut<PendingCommanderMoves>,
    mut zone_transitions: EventWriter<ZoneTransitionEvent>,
    mut player_choices: EventWriter<PlayerChoiceEvent>,
    commanders: Query<(Entity, &Owner), With<Commander>>,
    zones: Res<Zones>,
) {
    // Review all pending commander moves during state-based action check
    for (commander, move_info) in pending_moves.commanders.iter() {
        if let Ok((entity, owner)) = commanders.get(*commander) {
            // Offer choice to move to command zone
            player_choices.send(PlayerChoiceEvent {
                player: owner.0,
                choice_type: ChoiceType::CommandZoneOption {
                    commander: entity,
                    current_zone: move_info.current_zone,
                },
                timeout: Duration::from_secs(30),
            });
        }
    }
}

/// Response handler for command zone choice
pub fn handle_command_zone_choice(
    mut commands: Commands,
    mut choice_responses: EventReader<PlayerChoiceResponse>,
    mut zone_transitions: EventWriter<ZoneTransitionEvent>,
    mut pending_moves: ResMut<PendingCommanderMoves>,
) {
    for response in choice_responses.read() {
        if let ChoiceType::CommandZoneOption { commander, current_zone } = &response.choice_type {
            if response.choice == "command_zone" {
                // Player chose to move commander to command zone
                zone_transitions.send(ZoneTransitionEvent {
                    entity: *commander,
                    from: *current_zone,
                    to: Zone::Command,
                    cause: TransitionCause::CommanderRule,
                });
            }
            
            // Remove from pending moves either way
            pending_moves.commanders.remove(commander);
        }
    }
}
}

Step 3: Death Trigger Processing

The death triggers themselves work normally since the commander actually enters the graveyard:

#![allow(unused)]
fn main() {
/// System that processes death triggers
pub fn process_death_triggers(
    mut commands: Commands,
    mut zone_events: EventReader<ZoneTransitionEvent>,
    mut triggered_abilities: EventWriter<TriggeredAbilityEvent>,
    death_triggers: Query<(Entity, &DiesTriggeredAbility, &Owner)>,
) {
    for event in zone_events.read() {
        // Check for dies triggers (battlefield to graveyard)
        if event.from == Zone::Battlefield && event.to == Zone::Graveyard {
            if let Ok((entity, ability, owner)) = death_triggers.get(event.entity) {
                // Trigger the ability
                triggered_abilities.send(TriggeredAbilityEvent {
                    source: entity,
                    ability_id: ability.id,
                    controller: owner.0,
                    trigger_cause: TriggerCause::ZoneChange {
                        entity,
                        from: event.from,
                        to: event.to,
                    },
                });
            }
        }
    }
}
}

Timing and Implementation Considerations

The timing of the commander movement is important:

1. The death trigger must be processed before the commander moves to the command zone
2. The state-based action check that offers the command zone option must happen after death triggers are put on the stack
3. The commander stays in the graveyard (or other zone) until the command zone choice is made

#![allow(unused)]
fn main() {
// System ordering for proper death trigger handling
fn build_systems(app: &mut App) {
    app.add_systems(Update, (
        track_commander_zone_transitions,
        process_death_triggers,
        apply_state_based_actions,
        commander_zone_choice_sba
    ).chain());
}
}

Special Interactions

Several cards interact with commander death and zone changes in unique ways:

1. "Dies" Triggers on Commanders

Commanders with "When this creature dies" triggers will function normally:

#![allow(unused)]
fn main() {
pub fn create_elenda_the_dusk_rose() -> impl Bundle {
    (
        CardName("Elenda, the Dusk Rose".to_string()),
        // Other card components...
        Commander,
        DiesTriggeredAbility {
            id: AbilityId::new(),
            effect: Box::new(ElendaDeathEffect),
        },
    )
}
}

2. Commanders with Recursion Abilities

Some commanders have abilities that can return them from the graveyard:

#![allow(unused)]
fn main() {
pub fn create_gisa_and_geralf() -> impl Bundle {
    (
        CardName("Gisa and Geralf".to_string()),
        // Other card components...
        Commander,
        // Ability to cast zombie cards from graveyard
        ActivatedAbility {
            id: AbilityId::new(),
            cost: AbilityCost::None,
            effect: Box::new(CastZombieFromGraveyardEffect),
            timing_restriction: TimingRestriction::YourTurn,
            zone_restriction: ZoneRestriction::OnBattlefield,
        },
    )
}
}

3. Graveyard Replacement Effects

Effects that replace going to the graveyard (like Rest in Peace) interact with commanders:

#![allow(unused)]
fn main() {
pub fn handle_rest_in_peace_effect(
    mut zone_events: EventReader<ZoneTransitionEvent>,
    mut modified_zone_events: EventWriter<ModifiedZoneTransitionEvent>,
    rest_in_peace_effects: Query<&ReplacementEffect>,
) {
    for event in zone_events.read() {
        if event.to == Zone::Graveyard {
            // Check if Rest in Peace or similar effect is active
            if has_active_graveyard_replacement(&rest_in_peace_effects) {
                // This will affect commander death triggers
                modified_zone_events.send(ModifiedZoneTransitionEvent {
                    original: event.clone(),
                    modified_to: Zone::Exile,
                    cause: TransitionCause::ReplacementEffect {
                        effect_name: "Rest in Peace".to_string(),
                    },
                });
            }
        }
    }
}
}

Commander Death and State-Based Actions

The rules for commander death interact with multiple state-based actions:

#![allow(unused)]
fn main() {
pub fn apply_state_based_actions(
    mut commands: Commands,
    mut game_state: ResMut<GameState>,
    // ... other queries
) {
    // Only check when a player would receive priority
    if !should_check_sba(&game_state) {
        return;
    }
    
    // Check various state-based actions
    // ...
    
    // Process pending commander moves
    commander_zone_choice_sba(/* ... */);
    
    // Mark that we've checked SBAs
    game_state.last_sba_check = Instant::now();
}
}

User Interface Considerations

The UI for commander death requires special handling:

1. Prompt for command zone choice must be clear and timely
2. Visual indication of commanders in non-command zones is needed
3. Death triggers should be shown clearly when applicable

Testing Commander Death Triggers

#![allow(unused)]
fn main() {
#[test]
fn test_commander_death_triggers() {
    let mut app = App::new();
    app.add_systems(Startup, setup_test);
    app.add_systems(Update, (
        track_commander_zone_transitions,
        process_death_triggers,
        commander_zone_choice_sba,
        handle_command_zone_choice,
    ));
    
    // Create test entities
    let player = app.world.spawn_empty().id();
    
    // Create a commander with a death trigger
    let commander = app.world.spawn((
        CardName("Test Commander".to_string()),
        Commander,
        Owner(player),
        DiesTriggeredAbility {
            id: AbilityId::new(),
            effect: Box::new(TestDeathEffect),
        },
    )).id();
    
    // Move commander from battlefield to graveyard
    app.world.send_event(ZoneTransitionEvent {
        entity: commander,
        from: Zone::Battlefield,
        to: Zone::Graveyard,
        cause: TransitionCause::Destroy,
    });
    
    app.update();
    
    // Verify death trigger happened
    let triggered = app.world.resource::<TestState>().death_trigger_happened;
    assert!(triggered, "Death trigger should have happened");
    
    // Choose to move to command zone
    app.world.send_event(PlayerChoiceResponse {
        player: player,
        choice_type: ChoiceType::CommandZoneOption {
            commander: commander,
            current_zone: Zone::Graveyard,
        },
        choice: "command_zone".to_string(),
    });
    
    app.update();
    
    // Verify commander is now in command zone
    let zones = app.world.resource::<Zones>();
    assert!(zones.command.contains(&commander));
    assert!(!zones.graveyard.contains(&commander));
}
}

Related Documentation

• Command Zone: How the command zone works
• Commander Tax: How commander tax is applied
• State-Based Actions: How state-based actions interact with commander rules

Commander-Specific Cards

This document details the implementation of cards designed specifically for the Commander format.

Overview

Commander has become one of Magic: The Gathering's most popular formats, leading to the creation of cards specifically designed for it. These cards include:

1. Cards that explicitly reference the command zone or commanders
2. Cards designed to support multiplayer politics
3. Cards with mechanics only found in Commander products
4. Cards that interact with format-specific rules

Card Categories

Command Zone Interaction Cards

These cards directly interact with the command zone or commanders:

Command Zone Access

#![allow(unused)]
fn main() {
/// Component for effects that can access the command zone
#[derive(Component)]
pub struct CommandZoneAccessEffect {
    /// The type of interaction with the command zone
    pub interaction_type: CommandZoneInteraction,
}

/// Types of command zone interactions
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CommandZoneInteraction {
    /// Cast a card from the command zone (e.g., Command Beacon)
    CastFromZone,
    /// Return a card to the command zone (e.g., Leadership Vacuum)
    ReturnToZone,
    /// Copy a commander (e.g., Sakashima of a Thousand Faces)
    CopyCommander,
    /// Modify commander properties (e.g., Nevermore naming a commander)
    ModifyCommander,
}
}

Example implementation of Command Beacon:

#![allow(unused)]
fn main() {
pub fn create_command_beacon() -> impl Bundle {
    (
        CardName("Command Beacon".to_string()),
        CardType::Land,
        EntersTapped(false),
        ActivatedAbility {
            id: AbilityId::new(),
            cost: AbilityCost::Sacrifice(SacrificeCost::Self_),
            effect: Box::new(CommandBeaconEffect),
            timing_restriction: TimingRestriction::Sorcery,
            zone_restriction: ZoneRestriction::OnBattlefield,
        },
    )
}

/// Implementation of Command Beacon's effect
#[derive(Debug, Clone)]
pub struct CommandBeaconEffect;

impl AbilityEffect for CommandBeaconEffect {
    fn resolve(&self, world: &mut World, ability_ctx: &mut AbilityContext) {
        let source = ability_ctx.source;
        let controller = ability_ctx.controller;
        
        // Find commander in command zone
        if let Some(commander) = find_commander_in_command_zone(world, controller) {
            // Move commander to hand
            world.send_event(ZoneTransitionEvent {
                entity: commander,
                from: Zone::Command,
                to: Zone::Hand,
                cause: TransitionCause::Ability {
                    source,
                    ability_name: "Command Beacon".to_string(),
                },
            });
        }
    }
}
}

Commander Cost Reduction

Cards that reduce or modify the cost of casting commanders:

#![allow(unused)]
fn main() {
/// Component for effects that modify commander costs
#[derive(Component)]
pub struct CommanderCostModifier {
    /// How the cost is modified
    pub modification: CostModification,
    /// Which commanders this applies to (all or specific)
    pub target: CommanderTarget,
}

/// Implementation of Emerald Medallion (reduces cost of green spells)
pub fn create_emerald_medallion() -> impl Bundle {
    (
        CardName("Emerald Medallion".to_string()),
        CardType::Artifact,
        StaticAbility {
            id: AbilityId::new(),
            effect: Box::new(ColorCostReductionEffect(Color::Green)),
            condition: StaticCondition::Always,
        },
    )
}
}

Multiplayer Politics Cards

Cards designed for multiplayer political interactions:

#![allow(unused)]
fn main() {
/// Component for voting cards
#[derive(Component)]
pub struct VotingMechanic {
    /// The options players can vote for
    pub options: Vec<String>,
    /// What happens based on voting results
    pub resolution: VoteResolution,
}

/// Implementation of Council's Judgment
pub fn create_councils_judgment() -> impl Bundle {
    (
        CardName("Council's Judgment".to_string()),
        CardType::Sorcery,
        ManaCost::parse("{1}{W}{W}"),
        VotingMechanic {
            options: vec!["Exile".to_string()], // Each nonland permanent is an option
            resolution: VoteResolution::ExileMostVotes,
        },
    )
}

/// System that handles voting
pub fn handle_voting(
    mut commands: Commands,
    mut vote_events: EventReader<VoteEvent>,
    mut vote_results: EventWriter<VoteResultEvent>,
    voting_cards: Query<(Entity, &VotingMechanic, &Owner)>,
    players: Query<Entity, With<Player>>,
) {
    // Implementation details...
}
}

Commander-Specific Mechanics

Several mechanics were introduced specifically for Commander products:

Lieutenant

Cards with abilities that trigger if you control your commander:

#![allow(unused)]
fn main() {
/// Component for Lieutenant abilities
#[derive(Component)]
pub struct Lieutenant {
    /// The effect that happens when you control your commander
    pub effect: Box<dyn LieutenantEffect>,
}

/// Implementation of Thunderfoot Baloth
pub fn create_thunderfoot_baloth() -> impl Bundle {
    (
        CardName("Thunderfoot Baloth".to_string()),
        CardType::Creature,
        CreatureType(vec!["Beast".to_string()]),
        Power(5),
        Toughness(5),
        Lieutenant {
            effect: Box::new(ThunderfootBoostEffect),
        },
    )
}

/// System that checks for Lieutenant conditions
pub fn check_lieutenant_condition(
    mut commands: Commands,
    lieutenants: Query<(Entity, &Lieutenant, &Controller)>,
    commanders: Query<(Entity, &Commander, &Controller)>,
    mut effect_events: EventWriter<LieutenantEffectEvent>,
) {
    // For each lieutenant...
    for (lieutenant_entity, lieutenant, controller) in lieutenants.iter() {
        // Check if controller controls their commander
        let controls_commander = commanders
            .iter()
            .any(|(_, _, cmd_controller)| cmd_controller.0 == controller.0);
        
        // Apply or remove effect based on condition
        effect_events.send(LieutenantEffectEvent {
            lieutenant: lieutenant_entity,
            active: controls_commander,
        });
    }
}
}

Join Forces

Cards that allow all players to contribute mana to a spell:

#![allow(unused)]
fn main() {
/// Component for Join Forces mechanic
#[derive(Component)]
pub struct JoinForces {
    /// What happens based on mana contributed
    pub effect: Box<dyn JoinForcesEffect>,
    /// Which players can contribute
    pub contributor_restriction: ContributorRestriction,
}

/// Implementation of Minds Aglow
pub fn create_minds_aglow() -> impl Bundle {
    (
        CardName("Minds Aglow".to_string()),
        CardType::Sorcery,
        ManaCost::parse("{U}"),
        JoinForces {
            effect: Box::new(MindsAglowDrawEffect),
            contributor_restriction: ContributorRestriction::All,
        },
    )
}
}

Monarch

The Monarch mechanic introduces a special designation that players can claim, providing card advantage:

#![allow(unused)]
fn main() {
/// Component marking a player as the Monarch
#[derive(Component)]
pub struct Monarch;

/// Resource tracking the current monarch
#[derive(Resource)]
pub struct MonarchState {
    /// The current monarch, if any
    pub current_monarch: Option<Entity>,
    /// When the monarchy was last changed
    pub last_changed: Option<f32>,
}

/// System that handles the Monarch end-of-turn trigger
pub fn monarch_end_step_trigger(
    time: Res<Time>,
    monarch_state: Res<MonarchState>,
    mut turn_events: EventReader<EndStepEvent>,
    mut card_draw_events: EventWriter<DrawCardEvent>,
) {
    for event in turn_events.read() {
        if let Some(monarch) = monarch_state.current_monarch {
            if event.player == monarch {
                // Monarch draws a card at end of their turn
                card_draw_events.send(DrawCardEvent {
                    player: monarch,
                    amount: 1,
                    source: None,
                    reason: DrawReason::Ability("Monarch".to_string()),
                });
            }
        }
    }
}

/// System that transfers the Monarch when combat damage is dealt to them
pub fn monarch_combat_damage_transfer(
    mut commands: Commands,
    mut monarch_state: ResMut<MonarchState>,
    mut combat_damage_events: EventReader<CombatDamageEvent>,
    players: Query<Entity, With<Player>>,
) {
    for event in combat_damage_events.read() {
        if let Some(current_monarch) = monarch_state.current_monarch {
            if event.defending_player == current_monarch {
                // Transfer monarchy to attacking player
                if let Some(monarch_component) = commands.get_entity(current_monarch) {
                    monarch_component.remove::<Monarch>();
                }
                
                if let Some(new_monarch) = commands.get_entity(event.attacking_player_controller) {
                    new_monarch.insert(Monarch);
                    monarch_state.current_monarch = Some(event.attacking_player_controller);
                    monarch_state.last_changed = Some(time.elapsed_seconds());
                }
            }
        }
    }
}
}

Myriad

Myriad creates token copies attacking each opponent:

#![allow(unused)]
fn main() {
/// Component for the Myriad ability
#[derive(Component)]
pub struct Myriad;

/// System that handles Myriad triggers
pub fn handle_myriad_attacks(
    mut commands: Commands,
    mut declare_attacker_events: EventReader<DeclareAttackerEvent>,
    myriad_creatures: Query<Entity, With<Myriad>>,
    players: Query<Entity, With<Player>>,
    controllers: Query<&Controller>,
) {
    for event in declare_attacker_events.read() {
        if myriad_creatures.contains(event.attacker) {
            let attacker_controller = controllers.get(event.attacker).map(|c| c.0).unwrap_or_default();
            
            // Create token copies attacking each other opponent
            for potential_defender in players.iter() {
                // Skip the attacking player and the already-targeted defender
                if potential_defender == attacker_controller || potential_defender == event.defender {
                    continue;
                }
                
                // Create a token copy attacking this opponent
                let token = commands.spawn((
                    // Copy relevant components from original
                    // Add attacking status to new opponent
                    AttackingStatus {
                        defending_player: potential_defender,
                    },
                    TokenCopy {
                        original: event.attacker,
                        // Myriad tokens are exiled at end of combat
                        exile_at_end_of_combat: true,
                    },
                )).id();
                
                // More token setup...
            }
        }
    }
}
}

Melee

Melee gives a bonus based on how many opponents were attacked:

#![allow(unused)]
fn main() {
/// Component for the Melee ability
#[derive(Component)]
pub struct Melee {
    /// Bonus per opponent attacked
    pub bonus: i32,
}

/// System that calculates Melee bonuses
pub fn calculate_melee_bonuses(
    mut commands: Commands,
    mut declare_attackers_step_events: EventReader<DeclareAttackersStepEvent>,
    melee_creatures: Query<(Entity, &Melee, &Controller)>,
    mut attacking_status: Query<&AttackingStatus>,
    players: Query<Entity, With<Player>>,
) {
    for event in declare_attackers_step_events.read() {
        // For each creature with Melee...
        for (melee_entity, melee, controller) in melee_creatures.iter() {
            // Count distinct opponents attacked
            let opponents_attacked = attacking_status
                .iter()
                .filter(|status| {
                    // Only count attacks from controller's creatures
                    if let Ok(attacker_controller) = controllers.get(status.attacker) {
                        attacker_controller.0 == controller.0 && status.defending_player != controller.0
                    } else {
                        false
                    }
                })
                .map(|status| status.defending_player)
                .collect::<HashSet<Entity>>()
                .len();
                
            // Apply Melee bonus based on opponents attacked
            commands.entity(melee_entity).insert(MeleeBoost {
                power_bonus: melee.bonus * opponents_attacked as i32,
                toughness_bonus: melee.bonus * opponents_attacked as i32,
                expires_at: ExpiryTiming::EndOfTurn,
            });
        }
    }
}
}

Goad

Goad forces creatures to attack players other than you:

#![allow(unused)]
fn main() {
/// Component marking a creature as Goaded
#[derive(Component)]
pub struct Goaded {
    /// The player who applied the goad effect
    pub goaded_by: Entity,
    /// When the goad effect expires
    pub expires_at: ExpiryTiming,
}

/// System that enforces Goad restrictions during attacks
pub fn enforce_goad_restrictions(
    goaded_creatures: Query<(Entity, &Goaded)>,
    mut attack_validation_events: EventReader<ValidateAttackEvent>,
    mut attack_response_events: EventWriter<AttackValidationResponse>,
) {
    for event in attack_validation_events.read() {
        if let Ok((_, goaded)) = goaded_creatures.get(event.attacker) {
            // If attacking the player who goaded this creature, attack is invalid
            if event.defender == goaded.goaded_by {
                attack_response_events.send(AttackValidationResponse {
                    attacker: event.attacker,
                    defender: event.defender,
                    is_valid: false,
                    reason: "This creature is goaded and must attack a different player if able".to_string(),
                });
            }
        }
    }
}

/// System that enforces Goad requirements to attack if able
pub fn enforce_goad_attack_requirement(
    goaded_creatures: Query<(Entity, &Goaded, &CanAttack, &Controller)>,
    mut attack_requirement_events: EventReader<AttackRequirementCheckEvent>,
    mut attack_required_events: EventWriter<AttackRequiredEvent>,
    players: Query<Entity, With<Player>>,
) {
    for event in attack_requirement_events.read() {
        for (goaded_entity, goaded, can_attack, controller) in goaded_creatures.iter() {
            // If creature can attack and is controlled by current player
            if can_attack.0 && controller.0 == event.attacking_player {
                // Find valid attack targets (not the player who goaded)
                let valid_targets: Vec<Entity> = players
                    .iter()
                    .filter(|player| *player != goaded.goaded_by && *player != controller.0)
                    .collect();
                
                // If there are valid targets, this creature must attack
                if !valid_targets.is_empty() {
                    attack_required_events.send(AttackRequiredEvent {
                        creature: goaded_entity,
                        valid_targets,
                    });
                }
            }
        }
    }
}
}

Commander-Specific Cycles and Card Groups

Medallion Cycle

The Medallion cycle (Ruby Medallion, Sapphire Medallion, etc.) reduces costs for spells of specific colors:

#![allow(unused)]
fn main() {
pub fn create_ruby_medallion() -> impl Bundle {
    (
        CardName("Ruby Medallion".to_string()),
        CardType::Artifact,
        StaticAbility {
            id: AbilityId::new(),
            effect: Box::new(ColorCostReductionEffect(Color::Red)),
            condition: StaticCondition::Always,
        },
    )
}
}

Commander's Plate

A special equipment that gives protection from colors outside your commander's color identity:

#![allow(unused)]
fn main() {
pub fn create_commanders_plate() -> impl Bundle {
    (
        CardName("Commander's Plate".to_string()),
        CardType::Artifact,
        ArtifactType(vec!["Equipment".to_string()]),
        EquipCost(ManaCost::parse("{3}")),
        StaticAbility {
            id: AbilityId::new(),
            effect: Box::new(CommandersPlateEffect),
            condition: StaticCondition::IsEquipped,
        },
    )
}

#[derive(Debug, Clone)]
pub struct CommandersPlateEffect;

impl StaticEffect for CommandersPlateEffect {
    fn apply(&self, world: &mut World, source: Entity, target: Entity) {
        // Get equipped creature's controller
        let controller = world.get::<Controller>(target).unwrap().0;
        
        // Get controller's commanders' color identity
        let commander_identity = get_commander_color_identity(world, controller);
        
        // Grant protection from colors outside that identity
        let protection_colors = ALL_COLORS.iter()
            .filter(|color| !commander_identity.contains(**color))
            .copied()
            .collect();
        
        world.entity_mut(target).insert(Protection {
            protection_from: ProtectionType::Colors(protection_colors),
            source,
        });
        
        // Also grant stat boosts
        world.entity_mut(target).insert(StatBoost {
            power: 3,
            toughness: 3,
            source,
        });
    }
}
}

Testing Commander-Specific Cards