ptg 0.1.0__py3-none-any.whl

ptg/__init__.py

@@ -0,0 +1,8 @@
+"""PTG — Python Trading Card Game engine.
+
+Usage:
+    from ptg.api import Game, Player, CardDefinition, ...
+"""
+
+# Keep __init__.py light to avoid circular imports during testing.
+# For the single-import public API, use:  from ptg.api import ...

ptg/abilities/__init__.py

@@ -0,0 +1,6 @@
+from .resolver import register_card_triggers, unregister_card_triggers
+
+__all__ = [
+    "register_card_triggers",
+    "unregister_card_triggers",
+]

ptg/abilities/resolver.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+from ..engine.event_bus import GameEvent, EventBus
+from ..engine.spawn import process_spawns, process_leave_events
+from ..core.types import CardID
+from ..engine.types import CardDefinition
+from ..core.enums import AbilityType
+from ..engine.targeting import resolve_target
+
+if TYPE_CHECKING:
+    from ..engine.game import GameState
+
+# Resolves abilities that occur automatically when a condition is met in the game.
+# They require no player action or mana expenditure at that time.
+
+def register_card_triggers(bus: EventBus, card_id: CardID, card_def: CardDefinition) -> None:
+    """Suscribe card alterations of type "triggered" to the event bus based on their defined triggers.
+    This function iterates through the card's effects and their alterations.
+    """
+    for ability in (card_def.abilities or []):
+        if ability.ability_type != AbilityType.TRIGGERED:
+            continue
+        for alteration in ability.alterations:
+            trigger = alteration.start_trigger
+
+            def make_listener(trigger, alteration, card_id):
+                def listener(event, state):
+                    if event.type != trigger:
+                        return state
+                    resolved = resolve_target(
+                        state, alteration.target,
+                        source_card_id=card_id,
+                    )
+                    if resolved is None:
+                        return state
+                    state = alteration.effect.apply(state, resolved, **alteration.params)
+                    state = process_leave_events(state, bus)
+                    return process_spawns(state, bus)
+                return listener
+
+            bus.subscribe(trigger, make_listener(trigger, alteration, card_id), card_id)
+
+def unregister_card_triggers(bus: EventBus, card_id: CardID) -> None:
+    bus.unsubscribe_card(card_id)

ptg/actions/__init__.py

@@ -0,0 +1,9 @@
+from .registry import register_action, get_action, list_actions
+from .base import Action
+
+__all__ = [
+    "register_action",
+    "get_action",
+    "list_actions",
+    "Action",
+]

ptg/actions/activate_ability.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+from ..engine.event_bus import EventBus, GameEvent, EventType
+from ..engine.spawn import process_spawns, process_leave_events
+from ..engine.targeting import resolve_target
+from ..core.types import PlayerID, CardID
+from ..effects.spend_mana import SpendManaEffect
+from ..core.enums import AbilityType
+from .base import Action
+from .registry import register_action
+
+if TYPE_CHECKING:
+    from ..engine.game import GameState
+
+@register_action("activate_ability")
+class ActivateAbilityAction(Action):
+    def validate(self, state: GameState, player_id: PlayerID, card_id: CardID, ability_index: int) -> None:
+        """Validate if the ability can be activated."""
+        card = state.all_cards[card_id]
+        ability = card.card_definition.abilities[ability_index]
+
+        if ability.ability_type != AbilityType.ACTIVATED:
+            raise ValueError("The specified ability is not an activated ability.")
+
+        if card_id not in state.battlefield[player_id]:
+            raise ValueError("The card is not on the battlefield for this player.")
+        
+        player = state.players[player_id]
+        if not player.mana_pool.can_afford(ability.mana_requirement):
+            raise ValueError("Not enough mana to activate the ability.")
+
+    def execute(self, state: GameState, bus: EventBus, player_id: PlayerID, card_id: CardID, ability_index: int) -> GameState:
+        """Execute the activation of the ability."""
+        card = state.all_cards[card_id]
+        ability = card.card_definition.abilities[ability_index]
+
+        # Pay the mana cost
+        state = SpendManaEffect().apply(state, player_id, ability.mana_requirement)
+
+        # Apply the ability's alterations
+        for alteration in ability.alterations:
+            resolved = resolve_target(
+                state, alteration.target,
+                source_card_id=card_id,
+                source_player_id=player_id,
+            )
+            if resolved is None:
+                continue
+            state = alteration.effect.apply(state, resolved, **alteration.params)
+            state = process_leave_events(state, bus)
+            state = process_spawns(state, bus)
+
+        # Emit an event for the ability activation
+        event = GameEvent(type=EventType.ON_ABILITY_ACTIVATED, source=card_id, target=None, context={})
+        state = bus.emit(event, state)
+
+        return state

ptg/actions/base.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+from ..engine.event_bus import EventBus
+
+if TYPE_CHECKING:
+    from ..engine.game import GameState
+
+class Action(ABC):
+    @abstractmethod
+    def validate(self, state: GameState, **kwargs) -> None: ...
+
+    @abstractmethod
+    def execute(self, state: GameState, bus: EventBus, **kwargs) -> GameState: ...
+
+    def __call__(self, state: GameState, bus: EventBus, **kwargs) -> GameState:
+        self.validate(state, **kwargs)
+        return self.execute(state, bus, **kwargs)

ptg/actions/declare_attack.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+from ..engine.event_bus import EventBus, GameEvent, EventType
+from ..core.types import CardID, PlayerID
+from .base import Action
+from .registry import register_action
+from ..engine.types import CombatGroup
+from dataclasses import replace
+
+if TYPE_CHECKING:
+    from ..engine.game import GameState
+
+@register_action("declare_attack")
+class DeclareAttackAction(Action):
+    def validate(self, state: GameState, player_id: PlayerID, attacker_id: CardID) -> None:
+        """Validate that the attack can be declared."""
+        # Check if the attacker is on the battlefield and belongs to the player
+        if attacker_id not in state.battlefield.get(player_id, []):
+            raise ValueError(f"Card {attacker_id} is not on the battlefield for player {player_id}.")
+        
+        # Check if the card is alive and has not attacked this turn
+        attacker_card = state.all_cards[attacker_id]
+        if not attacker_card.is_alive:
+            raise ValueError(f"Card {attacker_id} is not alive and cannot attack.")
+        if attacker_card.attacked_this_turn:
+            raise ValueError(f"Card {attacker_id} has already attacked this turn.")
+        
+        # Card is not in pending combats
+        for combat in state.pending_combats:
+            if combat.attacker_id == attacker_id:
+                raise ValueError(f"Card {attacker_id} is already declared in a pending combat.")
+            
+    def execute(self, state: GameState, bus: EventBus, player_id: PlayerID, attacker_id: CardID) -> GameState:
+        """Execute the attack declaration."""
+        # Create a new combat group with no blockers
+        new_combat = CombatGroup(
+            attacker_id=attacker_id,
+            blocker_ids=[],
+            attacker_player_id=player_id,
+            defender_player_id=next(pid for pid in state.players if pid != player_id)  #Assuming a two-player game
+        )
+        # Add the new combat group to the pending combats
+        new_pending_combats = state.pending_combats + [new_combat]
+
+        # Mark the attacker as having attacked this turn
+        updated_attacker_card = state.all_cards[attacker_id]
+        updated_attacker_card = replace(updated_attacker_card, attacked_this_turn=True)
+
+        # Emit ON_ATTACK_DECLARED event
+        state = bus.emit(GameEvent(
+            type=EventType.ON_ATTACK_DECLARED,
+            source=attacker_id, target=None,
+            context={"attacker": updated_attacker_card}
+        ), state)
+
+        return replace(state, pending_combats=new_pending_combats, all_cards={**state.all_cards, attacker_id: updated_attacker_card})

ptg/actions/declare_defense.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+from ..engine.event_bus import EventBus, GameEvent, EventType
+from ..core.types import CardID, PlayerID
+from .base import Action
+from .registry import register_action
+from dataclasses import replace
+
+if TYPE_CHECKING:
+    from ..engine.game import GameState
+
+@register_action("declare_defense")
+class DeclareDefenseAction(Action):
+    def validate(self, state: GameState, player_id: PlayerID, blocker_id: CardID, combat_index: int) -> None:
+        """Validate that the defense can be declared."""
+        # Check if the combat index is valid
+        if combat_index < 0 or combat_index >= len(state.pending_combats):
+            raise ValueError(f"Combat index {combat_index} is out of range.")
+        
+        combat = state.pending_combats[combat_index]
+        
+        # Check if the blocker is on the battlefield and belongs to the player
+        if blocker_id not in state.battlefield.get(player_id, []):
+            raise ValueError(f"Card {blocker_id} is not on the battlefield for player {player_id}.")
+        
+        # Check if the combat_group's defender is the player declaring the defense
+        if combat.defender_player_id != player_id:
+            raise ValueError(f"Player {player_id} is not the defender in combat index {combat_index}.")
+        
+        # The blocker is not already blocking in this combat
+        if blocker_id in combat.blocker_ids:
+            raise ValueError(f"Card {blocker_id} is already declared as a blocker in combat index {combat_index}.")
+        
+        # Check if the blocker is alive
+        blocker_card = state.all_cards[blocker_id]
+        if not blocker_card.is_alive:
+            raise ValueError(f"Card {blocker_id} is not alive and cannot block.")
+        
+    def execute(self, state: GameState, bus: EventBus, player_id: PlayerID, blocker_id: CardID, combat_index: int) -> GameState:
+        """Execute the defense declaration."""
+        # Adds blocker_id to the combat_group's blocker_ids
+        combat = state.pending_combats[combat_index]
+        updated_combat = replace(combat, blocker_ids=combat.blocker_ids + [blocker_id])
+        state = replace(state, pending_combats=state.pending_combats[:combat_index] + [updated_combat] + state.pending_combats[combat_index+1:])
+
+        state = bus.emit(GameEvent(
+            type=EventType.ON_DEFENSE_DECLARED,
+            source=blocker_id, target=combat.attacker_id,
+            context={"blocker": state.all_cards[blocker_id], "attacker": state.all_cards[combat.attacker_id]}
+        ), state)
+
+        return state

ptg/actions/play_card.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+from dataclasses import replace
+from typing import TYPE_CHECKING
+from ..engine.event_bus import EventBus, GameEvent, EventType
+from ..engine.spawn import process_spawns, process_leave_events
+from ..engine.targeting import resolve_target
+from ..core.types import CardID, PlayerID, ManaRequirement, ManaPool
+from ..core.enums import CardType
+from ..effects.spend_mana import SpendManaEffect
+from ..abilities.resolver import register_card_triggers
+from .base import Action
+from .registry import register_action
+
+if TYPE_CHECKING:
+    from ..engine.game import GameState
+
+@register_action("play_card")
+class PlayCardAction(Action):
+    def validate(self, state: GameState, player_id: PlayerID, card_id: CardID) -> None:
+        # 1. The card is in the player's hand
+        if card_id not in state.hands.get(player_id, []):
+            raise ValueError(f"Card {card_id} is not in the hand of player {player_id}.")
+
+        card = state.all_cards[card_id]
+        card_def = card.card_definition
+
+        # 2. Can afford the mana cost of the card (if it's not a mana card)
+        if card_def.type != CardType.MANA:
+            mana_req = ManaRequirement(amounts=card_def.mana)
+            player = state.players[player_id]
+            if not player.mana_pool.can_afford(mana_req):
+                raise ValueError(f"Not enough mana to play {card_def.name}.")
+    
+    def execute(self, state: GameState, bus: EventBus, player_id: PlayerID, card_id: CardID) -> GameState:
+        card = state.all_cards[card_id]
+        card_def = card.card_definition
+
+        # 1. Remove the card from the player's hand
+        hand = list(state.hands.get(player_id, []))
+        hand.remove(card_id)
+        state = replace(state, hands={**state.hands, player_id: hand})
+
+        # 2. Pay the mana cost if it's not a mana card
+        if card_def.type != CardType.MANA:
+            mana_req = ManaRequirement(amounts=card_def.mana)
+            state = SpendManaEffect().apply(state, player_id, mana_req)
+
+        # 3. Resolve by card type
+        if card_def.type == CardType.CREATURE:
+            return self._play_creature(state, bus, player_id, card_id)
+        elif card_def.type == CardType.SPELL:
+            return self._play_spell(state, bus, player_id, card_id)
+        elif card_def.type == CardType.MANA:
+            return self._play_mana(state, bus, player_id, card_id)
+        return state
+    
+    def _play_creature(self, state: GameState, bus: EventBus, player_id: PlayerID, card_id: CardID)-> GameState:
+        card = state.all_cards[card_id]
+
+        # Add the card to the battlefield
+        bf = list(state.battlefield.get(player_id, []))
+        bf.append(card_id)
+        state = replace(state, battlefield={**state.battlefield, player_id: bf})
+
+        # Subscribe to card triggers
+        register_card_triggers(bus, card_id, card.card_definition)
+
+        # Send an event that the card has entered the battlefield
+        state = bus.emit(GameEvent(
+            type=EventType.ON_CARD_ENTER_BATTLEFIELD,
+            source=card_id, target=None,
+            context={}
+        ), state)
+
+        return state
+    
+    def _play_spell(self, state: GameState, bus: EventBus, player_id: PlayerID, card_id: CardID)-> GameState:
+        card = state.all_cards[card_id]
+
+        # Apply the spell's effects immediately
+        for ability in (card.card_definition.abilities or []):
+            for alteration in ability.alterations:
+                resolved = resolve_target(
+                    state, alteration.target,
+                    source_card_id=card_id,
+                    source_player_id=player_id,
+                )
+                if resolved is None:
+                    continue
+                state = alteration.effect.apply(state, resolved, **alteration.params)
+                state = process_leave_events(state, bus)
+                state = process_spawns(state, bus)
+
+        # To the graveyard after resolution
+        gy = list(state.graveyards.get(player_id, []))
+        gy.append(card_id)
+        state = replace(state, graveyards={**state.graveyards, player_id: gy})
+        state = bus.emit(GameEvent(
+            type=EventType.ON_CARD_ENTER_GRAVEYARD,
+            source=card_id, target=None,
+            context={"reason": "spell_resolution"}
+        ), state)
+
+        return state
+    
+    def _play_mana(self, state: GameState, bus: EventBus, player_id: PlayerID, card_id: CardID)-> GameState:
+        card = state.all_cards[card_id]
+        player = state.players[player_id]
+
+        # Add the mana to the player's mana pool
+        new_amounts = dict(player.mana_pool.amounts)
+        for mana_type, amount in card.card_definition.mana.items():
+            new_amounts[mana_type] = new_amounts.get(mana_type, 0) + amount
+
+        updated_player = replace(player, mana_pool=ManaPool(amounts=new_amounts))
+        state = replace(state, players={**state.players, player_id: updated_player})
+
+        # To the graveyard after resolution
+        gy = list(state.graveyards.get(player_id, []))
+        gy.append(card_id)
+        state = replace(state, graveyards={**state.graveyards, player_id: gy})
+        state = bus.emit(GameEvent(
+            type=EventType.ON_CARD_ENTER_GRAVEYARD,
+            source=card_id, target=None,
+            context={"reason": "mana_card_resolution"}
+        ), state)
+
+        # Emit an event that the player gained mana
+        state = bus.emit(GameEvent(
+            type=EventType.ON_PLAYER_MANA_GAINED,
+            source=card_id, target=player_id,
+            context={"amounts": card.card_definition.mana}
+        ), state)
+
+        return state

ptg/actions/registry.py

@@ -0,0 +1,22 @@
+from .base import Action
+
+ACTION_REGISTRY: dict[str, type] = {}
+
+def register_action(name: str):
+    """Register an action in the global registry."""
+    def decorator(cls: Action):
+        if name in ACTION_REGISTRY:
+            raise ValueError(f"Action with name '{name}' is already registered.")
+        ACTION_REGISTRY[name] = cls
+        return cls
+    return decorator
+
+def get_action(name: str) -> Action:
+    """Retrieve an action from the global registry by name."""
+    if name not in ACTION_REGISTRY:
+        raise ValueError(f"Action with name '{name}' is not registered.")
+    return ACTION_REGISTRY[name]
+
+def list_actions() -> list[str]:
+    """List all registered action names."""
+    return list(ACTION_REGISTRY.keys())

ptg/api.py

@@ -0,0 +1,41 @@
+"""Public API for the PTG engine. Import everything from here."""
+
+from .core.enums import CardType, ManaType, PhaseType, EventType, AbilityType, TargetSpec
+from .core.types import ManaRequirement, ManaPool, ManaCost
+from .engine.game import Game, GameState
+from .engine.player import Player
+from .engine.types import CardDefinition, CardInstance, CardAbility, AlterationData
+from .actions.play_card import PlayCardAction
+from .actions.declare_attack import DeclareAttackAction
+from .actions.declare_defense import DeclareDefenseAction
+from .actions.activate_ability import ActivateAbilityAction
+from .io.yaml_loader import load_card, load_cards_from_dir
+from .io.deck_builder import build_catalog, build_deck, load_deck
+
+__all__ = [
+    "CardType",
+    "ManaType",
+    "PhaseType",
+    "EventType",
+    "AbilityType",
+    "TargetSpec",
+    "ManaRequirement",
+    "ManaPool",
+    "ManaCost",
+    "Game",
+    "GameState",
+    "Player",
+    "CardDefinition",
+    "CardInstance",
+    "CardAbility",
+    "AlterationData",
+    "PlayCardAction",
+    "DeclareAttackAction",
+    "DeclareDefenseAction",
+    "ActivateAbilityAction",
+    "load_card",
+    "load_cards_from_dir",
+    "build_catalog",
+    "build_deck",
+    "load_deck",
+]

ptg/core/__init__.py

@@ -0,0 +1,18 @@
+from .enums import CardType, ManaType, PhaseType, EventType, EffectType, AbilityType, TargetSpec
+from .types import ManaCost, ManaRequirement, ManaPool, ActionData, CardID, PlayerID
+
+__all__ = [
+    "CardType",
+    "ManaType",
+    "PhaseType",
+    "EventType",
+    "EffectType",
+    "AbilityType",
+    "TargetSpec",
+    "ManaCost",
+    "ManaRequirement",
+    "ManaPool",
+    "ActionData",
+    "CardID",
+    "PlayerID",
+]

ptg/core/enums.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+from enum import Enum
+
+class CardType(Enum):
+    SPELL = "spell"
+    CREATURE = "creature"
+    MANA = "mana"
+
+class ManaType(Enum):
+    EARTH = "earth"
+    FIRE = "fire"
+    WATER = "water"
+    AIR = "air"
+    ANY = "any"
+
+class PhaseType(Enum):
+    DRAW = "draw"
+    MAIN = "main"
+    ATTACK = "attack"
+    DEFENSE = "defense"
+    END = "end"
+
+class EventType(Enum):
+    ON_CARD_DRAW = "on_card_draw"
+    ON_CARD_RECEIVE_DAMAGE = "on_card_receive_damage"
+    ON_CARD_DEATH = "on_card_death"
+    ON_CARD_HEALED = "on_card_healed"
+    ON_CARD_ATTACK = "on_card_attack"
+    ON_CARD_DEFENSE = "on_card_defense"
+
+    ON_CARD_ENTER_BATTLEFIELD = "on_card_enter_battlefield"
+    ON_CARD_ENTER_GRAVEYARD = "on_card_enter_graveyard"
+    ON_CARD_LEAVE_BATTLEFIELD = "on_card_leave_battlefield"
+    ON_CARD_LEAVE_GRAVEYARD = "on_card_leave_graveyard"
+    
+    ON_PLAYER_RECEIVE_DAMAGE = "on_player_receive_damage"
+    ON_PLAYER_DEATH = "on_player_death"
+    ON_PLAYER_MANA_SPENT = "on_player_mana_spent"
+    ON_PLAYER_MANA_GAINED = "on_player_mana_gained"
+    ON_PLAYER_HEALED = "on_player_healed"
+
+    ON_TURN_START = "on_turn_start"
+    ON_ATTACK_DECLARED = "on_attack_declared"
+    ON_DEFENSE_DECLARED = "on_defense_declared"
+    ON_COMBAT_RESOLVED = "on_combat_resolved"
+    ON_TURN_END = "on_turn_end"
+    ON_ABILITY_ACTIVATED = "on_ability_activated"
+
+class EffectType(Enum):
+    CARD = "card"
+    PLAYER = "player"
+
+class AbilityType(Enum):
+    TRIGGERED = "triggered"  # An ability that activates automatically when a specific condition is met.
+    ACTIVATED = "activated"  # An ability that requires a player to take an action, often involving a cost, to activate it.
+
+class TargetSpec(Enum):
+    SELF = "self"           # the card that has the ability or effect
+    OWNER = "owner"         # the player who controls the card
+    OPPONENT = "opponent"   # the opposing player
+
+class ZoneType(Enum):
+    HAND = "hand"
+    DECK = "deck"
+    BATTLEFIELD = "battlefield"
+    GRAVEYARD = "graveyard"

ptg/core/types.py

@@ -0,0 +1,61 @@
+from .enums import ManaType
+from typing import Any, NewType
+from dataclasses import dataclass, field
+
+@dataclass
+class ManaCost:
+    """Represents a single mana cost for playing a card or activating an effect."""
+    type: ManaType
+    amount: int
+
+@dataclass
+class ManaRequirement:
+    """Defines the mana requirements for playing a card or activating an effect."""
+    amounts: dict[ManaType, int] = field(default_factory=dict)
+
+@dataclass
+class ManaPool:
+    """Represents a player's mana pool, which tracks the amount of each 
+    type of mana available. Cannot contain "ANY" type mana.
+    """
+    amounts: dict[ManaType, int] = field(default_factory=dict)
+
+    def can_afford(self, requirement: ManaRequirement) -> bool:
+        any_needed = requirement.amounts.get(ManaType.ANY, 0)
+        remaining = dict(self.amounts)
+
+        for t, amt in requirement.amounts.items():
+            if t == ManaType.ANY:
+                continue
+            if remaining.get(t, 0) < amt:
+                return False
+            remaining[t] -= amt
+
+        return sum(remaining.values()) >= any_needed
+    
+    def spend(self, requirement: ManaRequirement) -> 'ManaPool':
+        new_amounts = dict(self.amounts)
+        any_needed = requirement.amounts.get(ManaType.ANY, 0)
+
+        for t, amt in requirement.amounts.items():
+            if t == ManaType.ANY:
+                continue
+            new_amounts[t] = new_amounts.get(t, 0) - amt
+
+        for t in list(new_amounts.keys()):
+            if any_needed <= 0:
+                break
+            if new_amounts[t] > 0:
+                spend = min(new_amounts[t], any_needed)
+                new_amounts[t] -= spend
+                any_needed -= spend
+
+        return ManaPool(amounts=new_amounts)
+
+@dataclass
+class ActionData:
+    name: str
+    params: dict[str, Any]
+
+CardID = NewType('CardID', str)
+PlayerID = NewType('PlayerID', str)

ptg/effects/__init__.py

@@ -0,0 +1,10 @@
+from .base import Effect
+from .registry import EFFECT_REGISTRY, register_effect, get_effect, list_effects
+
+__all__ = [
+    "Effect",
+    "EFFECT_REGISTRY",
+    "register_effect",
+    "get_effect",
+    "list_effects",
+]