mantimon-tcg/docs/ACTIVE_EFFECTS_DESIGN.md

# Active Effects System - Design Document

## Overview

The Active Effects System provides a centralized registry for persistent game modifiers that affect gameplay across multiple cards, turns, or the entire game. This system enables abilities, stadiums, and other cards to create lasting effects that modify damage calculations, energy counting, retreat costs, status immunity, and more.

### Goals

1. **Flexibility**: Support many types of persistent effects without hardcoding logic
2. **Discoverability**: Easy to query which effects are active and affecting a calculation
3. **Lifecycle Management**: Automatic cleanup when source cards leave play
4. **Stacking Rules**: Configurable rules for how multiple similar effects interact
5. **Debuggability**: Clear visibility into what effects are modifying game state

### Non-Goals (For Initial Implementation)

- Complex effect chains (effect A triggers effect B)
- Priority/speed systems (all effects of same type resolve together)
- Undo/replay support (effects are applied immediately)

---

## Data Model

### Enumerations

```python
class EffectTrigger(StrEnum):
    """When the effect should be evaluated."""
    CONTINUOUS = "continuous"        # Always active while source is in play
    ON_DAMAGE_CALC = "on_damage_calc"      # During damage calculation
    ON_ENERGY_COUNT = "on_energy_count"    # When counting energy for attack costs
    ON_RETREAT_CALC = "on_retreat_calc"    # When calculating retreat cost
    ON_STATUS_APPLY = "on_status_apply"    # When a status would be applied
    ON_TURN_START = "on_turn_start"        # At the start of a turn
    ON_TURN_END = "on_turn_end"            # At the end of a turn
    ON_ATTACK = "on_attack"                # When an attack is declared
    ON_KNOCKOUT = "on_knockout"            # When a Pokemon is knocked out


class EffectScope(StrEnum):
    """Who/what the effect applies to."""
    SELF = "self"                    # Only the source card
    TEAM_ACTIVE = "team_active"      # Owner's active Pokemon only
    TEAM_BENCH = "team_bench"        # Owner's benched Pokemon only
    TEAM_ALL = "team_all"            # All of owner's Pokemon
    OPPONENT_ACTIVE = "opponent_active"    # Opponent's active Pokemon
    OPPONENT_BENCH = "opponent_bench"      # Opponent's benched Pokemon
    OPPONENT_ALL = "opponent_all"          # All opponent's Pokemon
    ALL_POKEMON = "all_pokemon"            # Every Pokemon in play
    GLOBAL = "global"                      # Affects game rules


class StackingMode(StrEnum):
    """How multiple instances of the same effect combine."""
    ADDITIVE = "additive"      # Values sum (e.g., -10 + -10 = -20)
    MAX_ONLY = "max_only"      # Only strongest applies
    MIN_ONLY = "min_only"      # Only weakest applies
    NO_STACK = "no_stack"      # Only one instance allowed
```

### ActiveEffect Model

```python
class ActiveEffect(BaseModel):
    """A persistent effect active in the game.
    
    Active effects are registered when certain cards enter play (abilities,
    stadiums) or when certain actions occur. They are automatically removed
    when their source leaves play.
    
    Attributes:
        id: Unique identifier for this effect instance.
        effect_type: Category identifier for querying (e.g., "damage_reduction").
        source_type: What created this effect ("ability", "stadium", "attack", "trainer").
        source_card_id: Instance ID of the card providing this effect.
        source_player_id: Player who owns/controls the source.
        trigger: When this effect should be evaluated.
        scope: What this effect applies to.
        stacking_mode: How multiple instances combine.
        stacking_key: Key for stacking rules (effects with same key interact).
        params: Effect-specific parameters.
        duration: How long the effect lasts (None = until source leaves play).
        expires_turn: Turn number when effect expires (if duration-based).
        suppressed: If True, effect is temporarily disabled (e.g., by ability lock).
    """
    
    id: str
    effect_type: str
    source_type: str
    source_card_id: str | None = None  # None for game-wide effects
    source_player_id: str
    trigger: EffectTrigger = EffectTrigger.CONTINUOUS
    scope: EffectScope = EffectScope.SELF
    stacking_mode: StackingMode = StackingMode.ADDITIVE
    stacking_key: str | None = None  # For grouping similar effects
    params: dict[str, Any] = Field(default_factory=dict)
    duration: int | None = None  # None = permanent until source removed
    expires_turn: int | None = None
    suppressed: bool = False
```

### GameState Addition

```python
class GameState(BaseModel):
    # ... existing fields ...
    
    # Active effects registry
    active_effects: list[ActiveEffect] = Field(default_factory=list)
```

---

## Core Operations

### ActiveEffectsManager

```python
class ActiveEffectsManager:
    """Manages the lifecycle and querying of active effects."""
    
    def register_effect(
        self,
        game: GameState,
        effect_type: str,
        source_type: str,
        source_card_id: str | None,
        source_player_id: str,
        trigger: EffectTrigger,
        scope: EffectScope,
        params: dict[str, Any],
        stacking_mode: StackingMode = StackingMode.ADDITIVE,
        stacking_key: str | None = None,
        duration: int | None = None,
    ) -> ActiveEffect:
        """Register a new active effect.
        
        Generates a unique ID and adds the effect to the game's registry.
        Handles stacking rules if an effect with the same stacking_key exists.
        """
        ...
    
    def remove_effects_by_source(self, game: GameState, source_card_id: str) -> int:
        """Remove all effects from a specific source card.
        
        Called when a Pokemon leaves play (knockout, evolution, returned to hand).
        Returns the number of effects removed.
        """
        ...
    
    def remove_expired_effects(self, game: GameState) -> int:
        """Remove effects that have expired based on turn count."""
        ...
    
    def query_effects(
        self,
        game: GameState,
        effect_type: str | None = None,
        trigger: EffectTrigger | None = None,
        affecting_player_id: str | None = None,
        affecting_card_id: str | None = None,
        include_suppressed: bool = False,
    ) -> list[ActiveEffect]:
        """Query active effects matching the given criteria."""
        ...
    
    def get_combined_value(
        self,
        effects: list[ActiveEffect],
        param_key: str,
        base_value: int = 0,
    ) -> int:
        """Combine multiple effects into a single value respecting stacking modes."""
        ...
```

---

## Integration Points

### 1. Damage Calculation

The existing `_calculate_attack_damage` method would be extended:

```python
def _calculate_attack_damage(self, game, attacker, attacker_def, defender, defender_def, base_damage):
    damage = base_damage
    
    # Step 1: Attacker's damage modifier (existing)
    # Step 2: Query active effects - damage boost (attacker's team)
    boost_effects = self.effects_manager.query_effects(
        game,
        effect_type="damage_boost",
        trigger=EffectTrigger.ON_DAMAGE_CALC,
        affecting_card_id=attacker.instance_id,
    )
    if boost_effects:
        boost = self.effects_manager.get_combined_value(boost_effects, "amount")
        damage += boost
    
    # Step 3: Weakness (existing)
    # Step 4: Resistance (existing)
    
    # Step 5: Query active effects - damage reduction (defender's team)
    reduction_effects = self.effects_manager.query_effects(
        game,
        effect_type="damage_reduction",
        trigger=EffectTrigger.ON_DAMAGE_CALC,
        affecting_card_id=defender.instance_id,
    )
    if reduction_effects:
        reduction = self.effects_manager.get_combined_value(reduction_effects, "amount")
        damage -= reduction
    
    return max(0, damage)
```

### 2. Energy Counting

```python
def count_effective_energy(
    self,
    game: GameState,
    pokemon: CardInstance,
    player_id: str,
) -> dict[EnergyType, int]:
    """Count energy attached to a Pokemon, applying any multiplier effects."""
    counts: dict[EnergyType, int] = defaultdict(int)
    
    for energy in pokemon.attached_energy:
        energy_def = game.get_card_definition(energy.definition_id)
        for provided_type in energy_def.energy_provides:
            base_count = 1
            
            # Query energy multiplier effects
            multiplier_effects = self.effects_manager.query_effects(
                game,
                effect_type="energy_multiplier",
                trigger=EffectTrigger.ON_ENERGY_COUNT,
                affecting_card_id=pokemon.instance_id,
            )
            
            for effect in multiplier_effects:
                if effect.params.get("energy_type") == provided_type.value:
                    base_count *= effect.params.get("multiplier", 1)
            
            counts[provided_type] += base_count
    
    return counts
```

### 3. Retreat Cost Calculation

```python
def calculate_retreat_cost(
    self,
    game: GameState,
    pokemon: CardInstance,
    player_id: str,
) -> int:
    """Calculate effective retreat cost with modifiers."""
    card_def = game.get_card_definition(pokemon.definition_id)
    base_cost = card_def.retreat_cost if card_def else 0
    cost = base_cost + pokemon.retreat_cost_modifier
    
    # Query retreat cost reduction effects
    reduction_effects = self.effects_manager.query_effects(
        game,
        effect_type="retreat_cost_reduction",
        trigger=EffectTrigger.ON_RETREAT_CALC,
        affecting_card_id=pokemon.instance_id,
    )
    
    if reduction_effects:
        reduction = self.effects_manager.get_combined_value(reduction_effects, "amount")
        cost -= reduction
    
    # Check for free retreat effects
    free_effects = self.effects_manager.query_effects(
        game,
        effect_type="free_retreat",
        affecting_card_id=pokemon.instance_id,
    )
    if free_effects:
        cost = 0
    
    return max(0, cost)
```

### 4. Lifecycle Hooks

```python
def on_pokemon_enters_play(self, game: GameState, pokemon: CardInstance, player_id: str):
    """Called when a Pokemon enters the battlefield."""
    card_def = game.get_card_definition(pokemon.definition_id)
    if not card_def or not card_def.abilities:
        return
    
    for ability in card_def.abilities:
        if ability.effect_id and ability.effect_id.startswith("aura_"):
            self._register_ability_aura(game, pokemon, player_id, ability)


def on_pokemon_leaves_play(self, game: GameState, card_id: str):
    """Called when a Pokemon leaves the battlefield."""
    removed = self.effects_manager.remove_effects_by_source(game, card_id)
    if removed > 0:
        game.action_log.append({
            "type": "effects_removed",
            "source_card_id": card_id,
            "count": removed,
        })


def on_turn_end(self, game: GameState):
    """Called at the end of each turn."""
    self.effects_manager.remove_expired_effects(game)
```

---

## Effect Categories

Based on research of Genetic Apex (A1) and Mythical Island (A1a) card sets (~372 cards), the following effect patterns were identified:

### Ability Effects

| Effect Type | Example Card | Description |
|-------------|--------------|-------------|
| `energy_acceleration` | Gardevoir (Psy Shadow) | Attach Energy from Energy Zone to Active |
| `energy_multiplier` | Serperior (Jungle Totem) | Each Grass Energy provides 2 Grass Energy |
| `bench_snipe` | Greninja (Water Shuriken) | Deal damage to any opponent's Pokemon |
| `gust_basic` | Victreebel (Fragrance Trap) | Switch in opponent's Benched Basic |
| `auto_status` | Weezing (Gas Leak) | Automatically inflict status condition |
| `coinflip_status` | Hypno (Sleep Pendulum) | Coin flip to inflict status |
| `block_evolution` | Aerodactyl ex (Primeval Law) | Opponent can't evolve Active |

### Attack Effects

| Effect Type | Example Card | Description |
|-------------|--------------|-------------|
| `damage_per_bench_own` | Pikachu ex (Circle Circuit) | +X damage per own Benched Pokemon |
| `damage_per_bench_opp` | Pidgeot ex (Scattering Cyclone) | +X damage per opponent's Benched Pokemon |
| `damage_per_energy_coinflip` | Celebi ex (Powerful Bloom) | Flip coin per Energy, damage per heads |
| `damage_if_extra_energy` | Blastoise ex (Hydro Bazooka) | Bonus if extra Energy attached |
| `damage_if_status` | Muk (Venoshock) | Bonus if opponent is Poisoned |
| `damage_if_ko_last_turn` | Marshadow (Revenge) | Bonus if own Pokemon was KO'd |
| `self_bench_damage` | Zapdos (Raging Thunder) | Deal damage to own Bench |
| `discard_energy_self` | Charizard ex (Crimson Storm) | Discard Energy from self |
| `discard_energy_self_all` | Raichu (Thunderbolt) | Discard all Energy from self |
| `discard_energy_random_all` | Gyarados ex (Rampaging Whirlpool) | Discard random Energy from any Pokemon |
| `inflict_sleep` | Vileplume (Soothing Scent) | Opponent's Active is now Asleep |
| `inflict_poison` | Various | Opponent's Active is now Poisoned |
| `prevent_retreat` | Arbok (Corner) | Opponent can't retreat next turn |
| `block_supporters` | Gengar (Bother) | Opponent can't play Supporters next turn |
| `reduce_damage_next_turn` | Mr. Mime (Barrier Attack) | This Pokemon takes -X damage next turn |
| `heal_self` | Venusaur ex (Giant Bloom) | Heal damage from this Pokemon |
| `reveal_hand` | Mew (Psy Report) | Opponent reveals their hand |
| `copy_attack` | Mew ex (Genome Hacking) | Use opponent's Active's attack |

---

## Example Implementations

### Example 1: Serperior's "Jungle Totem" (Energy Multiplier)

**Card Definition:**
```python
CardDefinition(
    id="a1a-006-serperior",
    name="Serperior",
    card_type=CardType.POKEMON,
    stage=PokemonStage.STAGE_2,
    evolves_from="Servine",
    hp=110,
    pokemon_type=EnergyType.GRASS,
    abilities=[
        Ability(
            name="Jungle Totem",
            effect_id="aura_energy_multiplier",
            effect_params={
                "energy_type": "grass",
                "multiplier": 2,
            },
            effect_description="Each Grass Energy attached to your Grass Pokemon provides 2 Grass Energy. This effect doesn't stack.",
            uses_per_turn=None,  # Passive
        ),
    ],
    # ...
)
```

**Effect Handler:**
```python
@effect_handler("aura_energy_multiplier")
def handle_aura_energy_multiplier(ctx: EffectContext) -> EffectResult:
    """Register an energy multiplier aura."""
    energy_type = ctx.get_str_param("energy_type")
    multiplier = ctx.get_int_param("multiplier", 2)
    
    ctx.game.effects_manager.register_effect(
        game=ctx.game,
        effect_type="energy_multiplier",
        source_type="ability",
        source_card_id=ctx.source_card_id,
        source_player_id=ctx.source_player_id,
        trigger=EffectTrigger.ON_ENERGY_COUNT,
        scope=EffectScope.TEAM_ALL,
        params={
            "energy_type": energy_type,
            "multiplier": multiplier,
        },
        stacking_mode=StackingMode.NO_STACK,  # "This effect doesn't stack"
        stacking_key=f"energy_multiplier_{energy_type}",
    )
    
    return EffectResult.success_result(
        f"Jungle Totem: {energy_type} energy provides x{multiplier}",
    )
```

### Example 2: Greninja's "Water Shuriken" (Bench Snipe Ability)

**Card Definition:**
```python
CardDefinition(
    id="a1-089-greninja",
    name="Greninja",
    card_type=CardType.POKEMON,
    stage=PokemonStage.STAGE_2,
    hp=120,
    pokemon_type=EnergyType.WATER,
    abilities=[
        Ability(
            name="Water Shuriken",
            effect_id="deal_damage_any",
            effect_params={
                "damage": 20,
                "target": "opponent_any",
            },
            effect_description="Once during your turn, you may do 20 damage to 1 of your opponent's Pokemon.",
            uses_per_turn=1,
        ),
    ],
    # ...
)
```

**Effect Handler:**
```python
@effect_handler("deal_damage_any")
def handle_deal_damage_any(ctx: EffectContext) -> EffectResult:
    """Deal damage to any of opponent's Pokemon (requires target selection)."""
    damage = ctx.get_int_param("damage", 0)
    target_id = ctx.target_card_id  # Selected by player
    
    if not target_id:
        return EffectResult.failure_result("No target selected")
    
    # Find target Pokemon
    opponent = ctx.game.get_opponent(ctx.source_player_id)
    target = opponent.find_pokemon_in_play(target_id)
    
    if not target:
        return EffectResult.failure_result("Target not found")
    
    target.damage += damage
    
    return EffectResult.success_result(
        f"Water Shuriken dealt {damage} damage to {target_id}",
    )
```

### Example 3: Mr. Mime's "Barrier Attack" (Temporary Damage Reduction)

**Attack Definition:**
```python
Attack(
    name="Barrier Attack",
    cost=[EnergyType.PSYCHIC],
    damage=30,
    effect_id="reduce_damage_next_turn",
    effect_params={"reduction": 20},
    effect_description="During your opponent's next turn, this Pokemon takes -20 damage from attacks.",
)
```

**Effect Handler:**
```python
@effect_handler("reduce_damage_next_turn")
def handle_reduce_damage_next_turn(ctx: EffectContext) -> EffectResult:
    """Register a temporary damage reduction effect that lasts until end of opponent's next turn."""
    reduction = ctx.get_int_param("reduction", 0)
    
    ctx.game.effects_manager.register_effect(
        game=ctx.game,
        effect_type="damage_reduction",
        source_type="attack",
        source_card_id=ctx.source_card_id,
        source_player_id=ctx.source_player_id,
        trigger=EffectTrigger.ON_DAMAGE_CALC,
        scope=EffectScope.SELF,
        params={"amount": reduction},
        stacking_mode=StackingMode.ADDITIVE,
        duration=1,  # Expires after opponent's turn
    )
    
    return EffectResult.success_result(
        f"This Pokemon takes -{reduction} damage until end of opponent's next turn",
    )
```

### Example 4: Victreebel's "Fragrance Trap" (Gust Effect)

**Ability Definition:**
```python
Ability(
    name="Fragrance Trap",
    effect_id="gust_opponent_basic",
    effect_params={},
    effect_description="If this Pokemon is in the Active Spot, once during your turn, you may switch in 1 of your opponent's Benched Basic Pokemon to the Active Spot.",
    uses_per_turn=1,
)
```

**Effect Handler:**
```python
@effect_handler("gust_opponent_basic")
def handle_gust_opponent_basic(ctx: EffectContext) -> EffectResult:
    """Switch in one of opponent's Benched Basic Pokemon."""
    # Verify source is in Active Spot
    player = ctx.game.players[ctx.source_player_id]
    active = player.get_active_pokemon()
    
    if not active or active.instance_id != ctx.source_card_id:
        return EffectResult.failure_result("This Pokemon must be in the Active Spot")
    
    target_id = ctx.target_card_id
    if not target_id:
        return EffectResult.failure_result("No target selected")
    
    # Find target on opponent's bench
    opponent = ctx.game.get_opponent(ctx.source_player_id)
    target = opponent.bench.remove(target_id)
    
    if not target:
        return EffectResult.failure_result("Target not found on opponent's bench")
    
    # Verify it's a Basic Pokemon
    target_def = ctx.game.get_card_definition(target.definition_id)
    if target_def.stage != PokemonStage.BASIC:
        # Return to bench and fail
        opponent.bench.add(target)
        return EffectResult.failure_result("Target must be a Basic Pokemon")
    
    # Swap opponent's Active with target
    old_active = opponent.get_active_pokemon()
    if old_active:
        opponent.active.remove(old_active.instance_id)
        opponent.bench.add(old_active)
    
    opponent.active.add(target)
    
    return EffectResult.success_result(
        f"Switched {target_def.name} to opponent's Active Spot",
    )
```

---

## Suppression System

Some abilities can disable other abilities. This is handled via the `suppressed` flag:

```python
@effect_handler("suppress_abilities")
def handle_suppress_abilities(ctx: EffectContext) -> EffectResult:
    """Suppress all ability-based effects."""
    count = 0
    for effect in ctx.game.active_effects:
        if effect.source_type == "ability" and not effect.suppressed:
            effect.suppressed = True
            count += 1
    
    # Register suppression tracker
    ctx.game.effects_manager.register_effect(
        game=ctx.game,
        effect_type="ability_suppression",
        source_type="ability",
        source_card_id=ctx.source_card_id,
        source_player_id=ctx.source_player_id,
        trigger=EffectTrigger.CONTINUOUS,
        scope=EffectScope.GLOBAL,
        params={},
    )
    
    return EffectResult.success_result(f"Suppressed {count} ability effects")
```

When the suppressor leaves play, unsuppress all ability effects:

```python
def on_suppression_ends(game: GameState, suppressor_card_id: str):
    """Called when an ability suppressor leaves play."""
    for effect in game.active_effects:
        if effect.source_type == "ability":
            effect.suppressed = False
```

---

## File Structure

```
backend/app/core/
├── effects/
│   ├── __init__.py
│   ├── base.py              # EffectContext, EffectResult (existing)
│   ├── registry.py          # Effect handler registry (existing)
│   ├── handlers.py          # Built-in effect handlers (existing)
│   └── active_effects.py    # NEW: ActiveEffect, ActiveEffectsManager
├── engine.py                # Add effects_manager, integrate hooks
├── models/
│   └── game_state.py        # Add active_effects field
└── turn_manager.py          # Add lifecycle hooks
```

---

## Migration Path

1. **Phase 1**: Add `ActiveEffect` model and `ActiveEffectsManager` (no integration)
2. **Phase 2**: Add `active_effects` field to `GameState`
3. **Phase 3**: Integrate into damage calculation
4. **Phase 4**: Add lifecycle hooks (enter/leave play, turn boundaries)
5. **Phase 5**: Implement initial ability handlers
6. **Phase 6**: Integrate into energy counting, retreat cost, etc.

---

## Post-Launch TODO: Generic Modifier System

> **Priority: Low** - Implement when we encounter abilities that don't fit the named effect types.

For maximum flexibility with future card sets, a more generic modifier system could supplement the named effect types:

```python
class GenericModifier(BaseModel):
    """A generic numerical modifier for edge cases."""
    target: str           # "damage.taken", "energy.grass.count", "attack.cost.colorless"
    operation: str        # "add", "multiply", "set", "min", "max"
    value: int | float
    condition: str | None # Optional DSL: "attacker.type == fire"
```

**When to use:**
- When a new card's effect doesn't fit existing named types
- If `custom_modifier` is used frequently for similar patterns, promote to a named type

**Example:**
```python
ActiveEffect(
    effect_type="custom_modifier",
    params={
        "target": "damage.taken",
        "operation": "add",
        "value": -20,
        "condition": "attacker.type == fire",
        "description": "Reduces damage from Fire attacks by 20",
    },
)
```

---

## Open Questions

1. **Stacking limits**: Should there be a maximum total from stacked effects?
2. **Effect ordering**: When multiple effect types apply, is order significant?
3. **Visibility**: Should opponents see active effects, or only their own team's?
4. **Stadium effects**: Use this system, or keep as special case?
5. **Attack effects duration**: "During opponent's next turn" - when exactly does it expire?

---

## References

- [ARCHITECTURE.md](/docs/ARCHITECTURE.md) - Core engine architecture
- [GAME_RULES.md](/docs/GAME_RULES.md) - Game rules and mechanics
- [backend/app/core/effects/README.md](/backend/app/core/effects/README.md) - Effects module index