kaboom-engine 0.1.0__py3-none-any.whl

kaboom/__init__.py

@@ -0,0 +1,32 @@
+from .cards.card import Card, Suit, Rank
+from .players.player import Player
+from .game.game_state import GameState
+from .game.turn import apply_action, close_reaction, get_valid_actions, is_game_over
+from .game.actions import Draw, Discard, Replace, UsePower, CallKaboom
+from .game.results import ActionResult
+from .game.phases import GamePhase
+from .game.reaction import react_discard_own_cards, react_discard_other_cards, ReactionResult
+from .version import __version__
+
+__all__ = [
+    "Card",
+    "Suit",
+    "Rank",
+    "Player",
+    "GameState",
+    "apply_action",
+    "Draw",
+    "Discard",
+    "Replace",
+    "UsePower",
+    "CallKaboom", 
+    "react_discard_own_cards",
+    "react_discard_other_cards",
+    "ReactionResult",
+    "GamePhase",
+    "ActionResult",
+    "close_reaction",
+    "get_valid_actions",
+    "is_game_over",
+    "__version__"
+]

kaboom/cards/__init__.py

@@ -0,0 +1,4 @@
+# kaboom/cards/__init__.py
+from .card import Card, Rank, Suit
+
+__all__ = ["Card", "Rank", "Suit"]

kaboom/cards/card.py

@@ -0,0 +1,45 @@
+# kaboom/cards/card.py
+from enum import Enum
+from dataclasses import dataclass
+
+
+class Suit(str, Enum):
+    SPADES = "♠"
+    HEARTS = "♥"
+    DIAMONDS = "♦"
+    CLUBS = "♣"
+
+
+class Rank(str, Enum):
+    A = "A"
+    TWO = "2"
+    THREE = "3"
+    FOUR = "4"
+    FIVE = "5"
+    SIX = "6"
+    SEVEN = "7"
+    EIGHT = "8"
+    NINE = "9"
+    TEN = "10"
+    J = "J"
+    Q = "Q"
+    K = "K"
+
+
+@dataclass(frozen=True, slots=True)
+class Card:
+    rank: Rank
+    suit: Suit
+
+    def __str__(self) -> str:
+        return f"{self.rank.value}{self.suit.value}"
+    
+    @property
+    def score_value(self) -> int:
+        if self.rank == Rank.K and self.suit in {Suit.HEARTS, Suit.DIAMONDS}:
+            return 0
+        if self.rank == Rank.A:
+            return 1
+        if self.rank in {Rank.J, Rank.Q, Rank.K}:
+            return 10
+        return int(self.rank.value)

kaboom/exceptions.py

@@ -0,0 +1,16 @@
+# kaboom/exceptions.py
+class KaboomError(Exception):
+    """Base exception for Kaboom engine."""
+    pass
+
+class InvalidActionError(KaboomError):
+    """Raised when a player attempts an invalid action."""
+    pass
+
+class InvalidReactionError(KaboomError):
+    """Raised when a reaction attempt is invalid."""
+    pass
+
+class InvariantViolationError(KaboomError):
+    """Raised when game state invariants are violated."""
+    pass

kaboom/game/__init__.py

@@ -0,0 +1,10 @@
+# kaboom/game/__init__.py
+from .game_state import GameState
+from .reaction import react_discard_own_cards, react_discard_other_cards, ReactionResult
+from .actions import Draw, Discard, Replace, UsePower, CallKaboom
+from .turn import apply_action, close_reaction
+from .results import ActionResult
+from .phases import GamePhase
+
+__all__ = ["GameState", "react_discard_own_cards", "react_discard_other_cards", "ActionResult", "GamePhase",
+           "Draw", "Discard", "Replace", "UsePower", "CallKaboom", "apply_action", "close_reaction", "ReactionResult"]

kaboom/game/actions.py

@@ -0,0 +1,46 @@
+# kaboom/game/actions.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Protocol
+
+from kaboom.cards.card import Card
+
+class Action(Protocol):
+    """
+    Marker protocol for all turn actions.
+    """
+    actor_id: int
+
+@dataclass(frozen=True, slots=True)
+class Draw(Action):
+    actor_id: int
+
+@dataclass(frozen=True, slots=True)
+class Discard(Action):
+    actor_id: int
+
+@dataclass(frozen=True, slots=True)
+class Replace(Action):
+    actor_id: int
+    target_index: int   # index in player's hand
+
+@dataclass(frozen=True, slots=True)
+class UsePower(Action):
+    actor_id: int
+    power_name: str
+    source_card: Card
+
+    # Power-specific payload (indices, player ids, etc.)
+    target_player_id: Optional[int] = None
+    target_card_index: Optional[int] = None
+    second_target_player_id: Optional[int] = None
+    second_target_card_index: Optional[int] = None
+
+@dataclass(frozen=True, slots=True)
+class CallKaboom(Action):
+    actor_id: int
+
+@dataclass(frozen=True, slots=True)
+class CloseReaction(Action):
+    actor_id: int

kaboom/game/game_state.py

@@ -0,0 +1,134 @@
+# kaboom/game/game_state.py
+from __future__ import annotations
+import random
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+from kaboom.cards.card import Card
+from kaboom.players.player import Player
+from kaboom.exceptions import InvalidActionError
+from kaboom.game.phases import GamePhase
+
+@dataclass(slots=True)
+class GameState:
+    """
+    Complete mutable state of a Kaboom game.
+    """
+    players: List[Player]
+    deck: List[Card]
+    discard_pile: List[Card] = field(default_factory=list)
+    phase: GamePhase = GamePhase.TURN_DRAW
+
+    current_player_index: int = 0
+    round_number: int = 1
+
+    # Drawn card awaiting action
+    drawn_card: Optional[Card] = None
+
+    # Reaction state
+    reaction_rank: Optional[str] = None
+    reaction_initiator: Optional[int] = None
+    reaction_open: bool = False
+
+    # Kaboom
+    kaboom_called_by: Optional[int] = None
+    instant_winner: Optional[int] = None
+
+    def active_players(self) -> List[Player]:
+        return [p for p in self.players if p.active]
+
+    def current_player(self) -> Player:
+        return self.players[self.current_player_index]
+
+    # def advance_turn(self) -> None:
+    #     """
+    #     Move to next active player.
+    #     """
+    #     if self.kaboom_called_by is not None:
+    #         return
+
+    #     n = len(self.players)
+    #     for _ in range(n):
+    #         self.current_player_index = (self.current_player_index + 1) % n
+    #         if self.players[self.current_player_index].active:
+    #             break
+
+    #     if self.current_player_index == 0:
+    #         self.round_number += 1
+
+    def advance_turn(self) -> None:
+        """
+        Move to next player.
+
+        If Kaboom has been called, remaining players finish the round.
+        When the turn returns to the Kaboom caller, the game ends.
+        """
+
+        n = len(self.players)
+
+        while True:
+            self.current_player_index = (self.current_player_index + 1) % n
+
+            player = self.players[self.current_player_index]
+
+            # If Kaboom was called and we reached the caller again → end game
+            if (
+                self.kaboom_called_by is not None
+                and player.id == self.kaboom_called_by
+            ):
+                self.phase = GamePhase.GAME_OVER
+                return
+
+            # Skip inactive players (kaboom caller is inactive)
+            if player.active:
+                break
+
+        if self.current_player_index == 0:
+            self.round_number += 1
+
+    def top_discard(self) -> Optional[Card]:
+        return self.discard_pile[-1] if self.discard_pile else None
+    
+    def resolve_player(self, player_id: int) -> Player:
+        for p in self.players:
+            if p.id == player_id:
+                return p
+        raise InvalidActionError("Unknown player_id")
+
+    def ensure_deck(self) -> None:
+        """
+        Ensure deck has cards.
+        If empty, reshuffle discard pile (except top card).
+        """
+        if self.deck:
+            return
+
+        if len(self.discard_pile) <= 1:
+            raise InvalidActionError("No cards left to reshuffle.")
+
+        top = self.discard_pile.pop()
+        self.deck = self.discard_pile
+        random.shuffle(self.deck)
+
+        self.discard_pile = [top]
+
+    @classmethod
+    def new_game(cls, players: list[Player], deck: list[Card]) -> GameState:
+        """
+        Create a new game state with initial settings.
+        """
+
+        return cls(
+            players=players,
+            deck=deck,
+            discard_pile=[],
+            current_player_index=0,
+            round_number=1,
+            drawn_card=None,
+            reaction_rank=None,
+            reaction_initiator=None,
+            reaction_open=False,
+            kaboom_called_by=None,
+            instant_winner=None,
+        )

kaboom/game/phases.py

@@ -0,0 +1,8 @@
+# kaboom/game/phases.py
+from enum import Enum
+
+class GamePhase(str, Enum):
+    TURN_DRAW = "turn_draw"
+    TURN_RESOLVE = "turn_resolve"
+    REACTION = "reaction"
+    GAME_OVER = "game_over"

kaboom/game/reaction.py

@@ -0,0 +1,169 @@
+# kaboom/game/reaction.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, List
+
+from kaboom.exceptions import InvalidActionError
+from kaboom.game.game_state import GameState
+from kaboom.game.phases import GamePhase
+
+@dataclass(slots=True)
+class ReactionResult:
+    success: bool
+    penalty_applied: bool = False
+    instant_win_player: Optional[int] = None
+
+def _close_reaction(state: GameState) -> None:
+    state.reaction_open = False
+    state.reaction_rank = None
+    state.reaction_initiator = None
+    state.phase = GamePhase.TURN_DRAW
+
+def close_reaction(state: GameState) -> None:
+    if not state.reaction_open:
+        raise InvalidActionError("No reaction to close")
+
+    _close_reaction(state)
+    
+def _apply_penalty(state: GameState, actor_id: int) -> ReactionResult:
+    if not state.deck:
+        raise InvalidActionError("Deck empty during penalty.")
+
+    penalty_card = state.deck.pop()
+    state.resolve_player(actor_id).hand.append(penalty_card)
+
+    _close_reaction(state)
+    return ReactionResult(success=False, penalty_applied=True)
+
+def _check_instant_win(state: GameState, actor_id: int) -> ReactionResult:
+    if not state.resolve_player(actor_id).hand:
+        state.instant_winner = actor_id
+        state.phase = GamePhase.GAME_OVER
+        return ReactionResult(success=True, instant_win_player=actor_id)
+
+    return ReactionResult(success=True)
+
+def react_discard_own_card(
+    state: GameState,
+    actor_id: int,
+    card_index: int,
+) -> ReactionResult:
+    if not state.reaction_open:
+        raise InvalidActionError("No active reaction window.")
+
+    player = state.resolve_player(actor_id)
+
+    if card_index < 0 or card_index >= len(player.hand):
+        raise InvalidActionError("Invalid card index.")
+
+    card = player.hand[card_index]
+
+    if card.rank.value != state.reaction_rank:
+        return _apply_penalty(state, actor_id)
+
+    # Valid match
+    discarded = player.hand.pop(card_index)
+    state.discard_pile.append(discarded)
+
+    _close_reaction(state)
+    return _check_instant_win(state, actor_id)
+
+def react_discard_other_card(
+    state: GameState,
+    actor_id: int,
+    target_player_id: int,
+    target_card_index: int,
+    give_card_index: int,
+) -> ReactionResult:
+    if not state.reaction_open:
+        raise InvalidActionError("No active reaction window.")
+
+    actor = state.resolve_player(actor_id)
+    target = state.resolve_player(target_player_id)
+
+    if not actor.hand:
+        raise InvalidActionError("Actor must have a card to give.")
+
+    target_card = target.hand[target_card_index]
+
+    if target_card.rank.value != state.reaction_rank:
+        return _apply_penalty(state, actor_id)
+
+    # Discard target's card
+    discarded = target.hand.pop(target_card_index)
+    state.discard_pile.append(discarded)
+
+    # Give actor's card (hidden)
+    given = actor.hand.pop(give_card_index)
+    target.hand.append(given)
+
+    _close_reaction(state)
+    return ReactionResult(success=True)
+
+def react_discard_own_cards(
+    state: GameState,
+    actor_id: int,
+    card_indices: List[int],
+) -> ReactionResult:
+    if not state.reaction_open:
+        raise InvalidActionError("No active reaction window.")
+
+    if not card_indices:
+        raise InvalidActionError("Must discard at least one card.")
+
+    player = state.resolve_player(actor_id)
+
+    # Validate indices
+    if any(i < 0 or i >= len(player.hand) for i in card_indices):
+        raise InvalidActionError("Invalid card index.")
+
+    # Validate all ranks BEFORE mutating
+    for i in card_indices:
+        if player.hand[i].rank.value != state.reaction_rank:
+            return _apply_penalty(state, actor_id)
+
+    # Discard highest indices first (stable pop)
+    for i in sorted(card_indices, reverse=True):
+        discarded = player.hand.pop(i)
+        state.discard_pile.append(discarded)
+
+    _close_reaction(state)
+    return _check_instant_win(state, actor_id)
+
+def react_discard_other_cards(
+    state: GameState,
+    actor_id: int,
+    target_player_id: int,
+    target_card_indices: List[int],
+    give_card_indices: List[int],
+) -> ReactionResult:
+    if not state.reaction_open:
+        raise InvalidActionError("No active reaction window.")
+
+    if len(target_card_indices) != len(give_card_indices):
+        raise InvalidActionError("Must give one card per stolen card.")
+
+    actor = state.resolve_player(actor_id)
+    target = state.resolve_player(target_player_id)
+
+    if len(actor.hand) < len(give_card_indices):
+        raise InvalidActionError("Not enough cards to give.")
+
+    # Validate ranks first
+    for i in target_card_indices:
+        if target.hand[i].rank.value != state.reaction_rank:
+            return _apply_penalty(state, actor_id)
+
+    # Discard stolen cards
+    for i in sorted(target_card_indices, reverse=True):
+        discarded = target.hand.pop(i)
+        state.discard_pile.append(discarded)
+
+    # Give cards (hidden)
+    for i in sorted(give_card_indices, reverse=True):
+        given = actor.hand.pop(i)
+        target.hand.append(given)
+
+    _close_reaction(state)
+    return ReactionResult(success=True)

kaboom/game/results.py

@@ -0,0 +1,11 @@
+# kaboom/game/results.py
+from dataclasses import dataclass
+from typing import Optional
+
+@dataclass(slots=True)
+class ActionResult:
+    action: str
+    actor_id: int
+    reaction_opened: bool = False
+    reaction_closed: bool = False
+    instant_winner: Optional[int] = None

kaboom/game/turn.py

@@ -0,0 +1,204 @@
+# kaboom/game/turn.py
+from __future__ import annotations
+
+from kaboom.exceptions import InvalidActionError
+from kaboom.game.actions import (
+    Action,
+    Draw,
+    Discard,
+    Replace,
+    UsePower,
+    CallKaboom,
+    CloseReaction,
+)
+from kaboom.game.game_state import GameState
+from kaboom.game.validators import validate_index, validate_turn
+from kaboom.powers.registry import POWER_REGISTRY
+from kaboom.game.reaction import close_reaction
+from kaboom.game.results import ActionResult
+from kaboom.game.phases import GamePhase
+
+def _validate_turn_owner(state: GameState, actor_id: int) -> None:
+    current = state.current_player()
+    if current.id != actor_id:
+        raise InvalidActionError("Not this player's turn.")
+    if not current.active:
+        raise InvalidActionError("Inactive player cannot act.")
+
+
+def _draw(state: GameState, action: Draw) -> None:
+
+    if state.drawn_card is not None:
+        raise InvalidActionError("Already holding a drawn card.")
+
+    state.ensure_deck()
+
+    if not state.deck:
+        raise InvalidActionError("Deck is empty.")
+
+    state.drawn_card = state.deck.pop()
+    state.phase = GamePhase.TURN_RESOLVE
+
+def _replace(state: GameState, action: Replace) -> None:
+    if state.drawn_card is None:
+        raise InvalidActionError("No drawn card to replace with.")
+
+    player = state.current_player()
+
+    validate_index(len(player.hand), action.target_index, "target_index")
+
+    replaced = player.hand[action.target_index]
+    state.discard_pile.append(replaced)
+
+    player.hand[action.target_index] = state.drawn_card
+    state.drawn_card = None
+
+    # Open reaction window
+    state.reaction_rank = replaced.rank.value
+    state.reaction_initiator = player.id
+    state.reaction_open = True
+    state.phase = GamePhase.REACTION
+
+    state.advance_turn()
+
+def _discard(state: GameState, action: Discard) -> None:
+    if state.drawn_card is None:
+        raise InvalidActionError("No drawn card to discard.")
+
+    discarded = state.drawn_card
+    state.discard_pile.append(discarded)
+    state.drawn_card = None
+
+    state.reaction_rank = discarded.rank.value
+    state.reaction_initiator = action.actor_id
+    state.reaction_open = True
+    state.phase = GamePhase.REACTION
+
+    state.advance_turn()
+
+def _use_power(state: GameState, action: UsePower) -> None:
+    card = action.source_card
+
+    if state.drawn_card is None:
+        raise InvalidActionError("No drawn card to use power with.")
+
+    if state.drawn_card != card:
+        raise InvalidActionError("Power must use drawn card.")
+
+    for power in POWER_REGISTRY:
+        if power.can_apply(state, action.actor_id, card):
+            power.apply(state, action)
+            break
+    else:
+        raise InvalidActionError("No valid power for this card.")
+
+    state.discard_pile.append(card)
+    state.drawn_card = None
+    state.advance_turn()
+
+def _call_kaboom(state: GameState, action: CallKaboom) -> None:
+    if state.round_number <= 1:
+        raise InvalidActionError("Kaboom cannot be called in round 1.")
+
+    player = state.current_player()
+
+    state.kaboom_called_by = player.id
+    player.active = False
+    player.revealed = True
+
+def is_game_over(state: GameState) -> bool:
+    return state.phase == GamePhase.GAME_OVER
+    
+def get_valid_actions(state: GameState):
+    """
+    Return all valid actions for the current player.
+    Useful for AI agents and simulations.
+    """
+
+    if state.phase == GamePhase.GAME_OVER:
+        return []
+
+    player = state.current_player()
+    actions = []
+
+    if state.phase == GamePhase.REACTION:
+        actions.append(CloseReaction(actor_id=player.id))
+        return actions
+
+    if state.phase == GamePhase.TURN_DRAW:
+        actions.append(Draw(actor_id=player.id))
+
+        if state.round_number > 1:
+            actions.append(CallKaboom(actor_id=player.id))
+
+        return actions
+
+    if state.phase == GamePhase.TURN_RESOLVE:
+        actions.append(Discard(actor_id=player.id))
+
+        for i in range(len(player.hand)):
+            actions.append(Replace(actor_id=player.id, target_index=i))
+
+        return actions
+
+    return actions
+
+def apply_action(state: GameState, action: Action) -> list[ActionResult]:
+    """
+    Apply a validated action to the game state.
+    """
+    if state.phase == GamePhase.GAME_OVER:
+        raise InvalidActionError("Game is already over.")
+    
+    # ------------------------------------------------
+    # Reaction resolution path (bypass turn rules)
+    # ------------------------------------------------
+    if isinstance(action, CloseReaction):
+        close_reaction(state)
+        return [ActionResult("close_reaction", action.actor_id, reaction_closed=True, instant_winner=state.instant_winner)]
+    
+    # ------------------------------------------------
+    # Normal turn validation
+    # ------------------------------------------------
+    if state.reaction_open:
+        raise InvalidActionError("Reaction window open.")
+    _validate_turn_owner(state, action.actor_id)
+    validate_turn(state, action.actor_id)
+
+    phase = state.phase
+    
+    if phase == GamePhase.REACTION and not isinstance(action, CloseReaction):
+        raise InvalidActionError("Must resolve reaction first.")
+    
+    if phase == GamePhase.TURN_DRAW and not (isinstance(action, Draw) or isinstance(action, CallKaboom)):
+        raise InvalidActionError("Must draw first.")
+    
+    if phase == GamePhase.TURN_RESOLVE and isinstance(action, Draw):
+        raise InvalidActionError("Already drawn this turn.")
+
+    # ------------------------------------------------
+    # Turn actions
+    # ------------------------------------------------
+    
+    if isinstance(action, Draw):
+        _draw(state, action)
+        return [ActionResult("draw", action.actor_id)]
+
+    elif isinstance(action, Replace):
+        _replace(state, action)
+        return [ActionResult("replace", action.actor_id, reaction_opened=True)]
+
+    elif isinstance(action, Discard):
+        _discard(state, action)
+        return [ActionResult("discard", action.actor_id, reaction_opened=True)]
+
+    elif isinstance(action, UsePower):
+        _use_power(state, action)
+        return [ActionResult("use_power", action.actor_id)]
+
+    elif isinstance(action, CallKaboom):
+        _call_kaboom(state, action)
+        return [ActionResult("call_kaboom", action.actor_id)]
+    
+    else:
+        raise InvalidActionError(f"Unknown action type: {type(action)}")

kaboom/game/validators.py

@@ -0,0 +1,14 @@
+# kaboom/game/validators.py
+from kaboom.exceptions import InvalidActionError
+from kaboom.game.game_state import GameState
+
+def validate_turn(state: GameState, actor_id: int):
+    if state.current_player().id != actor_id:
+        raise InvalidActionError(f"Not this player's turn.")
+
+
+def validate_index(length: int, index: int, name: str):
+    if index is None:
+        raise InvalidActionError(f"{name} required.")
+    if index < 0 or index >= length:
+        raise InvalidActionError(f"{name} out of range.")

kaboom/players/__init__.py

@@ -0,0 +1,4 @@
+# kaboom/players/__init__.py
+from .player import Player
+
+__all__ = ["Player"]

kaboom/players/player.py

@@ -0,0 +1,49 @@
+# kaboom/players/player.py
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Dict, Tuple
+
+from kaboom.cards.card import Card
+
+
+@dataclass(slots=True)
+class Player:
+    """
+    Represents a single player and their private state.
+    """
+    id: int
+    name: str
+
+    hand: List[Card] = field(default_factory=list)
+
+    # Tracks which cards THIS player has seen
+    # (player_id, card_index) → Card
+    memory: Dict[Tuple[int, int], Card] = field(default_factory=dict)
+
+    active: bool = True      # False after Kaboom call
+    revealed: bool = False  # True only at final reveal
+
+    def card_count(self) -> int:
+        return len(self.hand)
+
+    def total_score(self) -> int:
+        return sum(card.score_value for card in self.hand)
+
+    def remove_card(self, index: int) -> Card:
+        return self.hand.pop(index)
+
+    def add_card(self, card: Card) -> None:
+        self.hand.append(card)
+
+    def remember(self, player_id: int, card_index: int, card: Card) -> None:
+        """
+        Store knowledge gained via a power.
+        """
+        self.memory[(player_id, card_index)] = card
+
+    def forget_all(self) -> None:
+        """
+        Used after blind swaps or Kaboom.
+        """
+        self.memory.clear()

kaboom/powers/__init__.py

@@ -0,0 +1,8 @@
+# kaboom/powers/__init__.py
+from .see_self import SeeSelfPower
+from .see_other import SeeOtherPower
+from .blind_swap import BlindSwapPower
+from .see_and_swap import SeeAndSwapPower
+from .registry import POWER_REGISTRY
+
+__all__ = ["SeeSelfPower", "SeeOtherPower", "BlindSwapPower", "SeeAndSwapPower", "POWER_REGISTRY"]

kaboom/powers/base.py

@@ -0,0 +1,14 @@
+# kaboom/powers/base.py
+from abc import ABC, abstractmethod
+from kaboom.game.game_state import GameState
+from kaboom.game.actions import UsePower
+
+
+class Power(ABC):
+    @abstractmethod
+    def can_apply(self, state: GameState, actor_id: int, card) -> bool:
+        ...
+
+    @abstractmethod
+    def apply(self, state: GameState, action: UsePower,) -> None:
+        ...

kaboom/powers/blind_swap.py

@@ -0,0 +1,26 @@
+# kaboom/powers/blind_swap.py
+from kaboom.game.actions import UsePower
+from kaboom.powers.base import Power
+from kaboom.cards.card import Rank
+from kaboom.game.game_state import GameState
+
+
+class BlindSwapPower(Power):
+    VALID_RANKS = {Rank.J, Rank.Q}
+
+    def can_apply(self, state, actor_id, card):
+        return card.rank in self.VALID_RANKS
+
+    def apply(self, state: GameState, action: UsePower) -> None:
+        actor = state.resolve_player(action.actor_id)
+        target = state.resolve_player(action.target_player_id)
+
+        actor.hand[action.target_card_index], target.hand[
+            action.second_target_card_index
+        ] = (
+            target.hand[action.second_target_card_index],
+            actor.hand[action.target_card_index],
+        )
+
+        actor.forget_all()
+        target.forget_all()

kaboom/powers/registry.py

@@ -0,0 +1,12 @@
+# kaboom/powers/registry.py
+from kaboom.powers.see_self import SeeSelfPower
+from kaboom.powers.see_other import SeeOtherPower
+from kaboom.powers.blind_swap import BlindSwapPower
+from kaboom.powers.see_and_swap import SeeAndSwapPower
+
+POWER_REGISTRY = [
+    SeeSelfPower(),
+    SeeOtherPower(),
+    BlindSwapPower(),
+    SeeAndSwapPower(),
+]

kaboom/powers/see_and_swap.py

@@ -0,0 +1,33 @@
+# kaboom/powers/see_and_swap.py
+from kaboom.powers.base import Power
+from kaboom.cards.card import Rank, Suit
+from kaboom.game.game_state import GameState
+from kaboom.game.actions import UsePower
+
+
+class SeeAndSwapPower(Power):
+    def can_apply(self, state, actor_id, card):
+        return card.rank == Rank.K and card.suit in {
+            Suit.SPADES,
+            Suit.CLUBS,
+        }
+
+    def apply(self, state: GameState, action: UsePower) -> None:
+        p1 = state.resolve_player(action.target_player_id)
+        p2 = state.resolve_player(action.second_target_player_id)
+
+        c1 = p1.hand[action.target_card_index]
+        c2 = p2.hand[action.second_target_card_index]
+
+        state.resolve_player(action.actor_id).remember(
+            action.target_player_id, action.target_card_index, c1
+        )
+        state.resolve_player(action.actor_id).remember(
+            action.second_target_player_id,
+            action.second_target_card_index,
+            c2,
+        )
+
+        p1.hand[action.target_card_index], p2.hand[
+            action.second_target_card_index
+        ] = c2, c1

kaboom/powers/see_other.py

@@ -0,0 +1,23 @@
+# kaboom/powers/see_other.py
+from kaboom.game.actions import UsePower
+from kaboom.powers.base import Power
+from kaboom.cards.card import Rank
+from kaboom.game.game_state import GameState
+
+
+class SeeOtherPower(Power):
+    VALID_RANKS = {Rank.NINE, Rank.TEN}
+
+    def can_apply(self, state, actor_id, card):
+        return card.rank in self.VALID_RANKS
+
+    def apply(self, state: GameState, action: UsePower) -> None:
+        target = state.resolve_player(action.target_player_id)
+        card = target.hand[action.target_card_index]
+ 
+        state.resolve_player(action.actor_id).remember(
+            action.target_player_id,
+            action.target_card_index,
+            card,
+        )
+

kaboom/powers/see_self.py

@@ -0,0 +1,19 @@
+# kaboom/powers/see_other.py
+from kaboom.game.actions import UsePower
+from kaboom.powers.base import Power
+from kaboom.cards.card import Rank
+from kaboom.game.game_state import GameState
+
+
+class SeeSelfPower(Power):
+    VALID_RANKS = {Rank.SEVEN, Rank.EIGHT}
+
+    def can_apply(self, state, actor_id, card):
+        return card.rank in self.VALID_RANKS
+
+    def apply(self, state: GameState, action: UsePower) -> None:
+        idx = action.target_card_index
+        player = state.resolve_player(action.actor_id)
+        card = player.hand[idx]
+        player.remember(action.actor_id, idx, card)
+

kaboom/version.py

@@ -0,0 +1,2 @@
+# kaboom/version.py
+__version__ = "0.1.0"

kaboom_engine-0.1.0.dist-info/METADATA

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: kaboom-engine
+Version: 0.1.0
+Summary: Core game engine for the Kaboom card game.
+Author: Arnav Ajay
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Kaboom Engine
+
+A deterministic Python engine for the **Kaboom card game**.
+
+The project implements the full game logic including turns, reactions, powers, and endgame rules, designed to be used as a reusable **simulation engine, AI environment, or UI backend**.
+
+---
+
+# Features
+
+* Complete Kaboom game rules
+* Deterministic turn engine
+* Reaction resolution system
+* Card power mechanics
+* Kaboom endgame logic
+* Deck reshuffle handling
+* Action-based engine architecture
+* Event-based results
+* Fully tested core logic
+
+The engine is designed so it can be used for:
+
+* CLI or graphical game clients
+* AI agents
+* game simulations
+* multiplayer servers
+* reinforcement learning environments
+
+---
+
+# Installation
+
+Clone the repository:
+
+```bash
+git clone https://github.com/Arnav-Ajay/kaboom-core.git
+cd kaboom-core
+```
+
+Install locally:
+
+```bash
+pip install -e .
+```
+
+---
+
+# Basic Usage
+
+```python
+from kaboom import GameState, apply_action
+from kaboom.game.actions import Draw, Discard
+
+state = GameState.new_game()
+
+apply_action(state, Draw(actor_id=0))
+apply_action(state, Discard(actor_id=0))
+```
+
+---
+
+# Running Simulations
+
+The engine supports automated play.
+
+```python
+import random
+from kaboom import GameState, apply_action
+from kaboom.game.turn import get_valid_actions
+
+state = GameState.new_game()
+
+while True:
+    actions = get_valid_actions(state)
+
+    if not actions:
+        break
+
+    action = random.choice(actions)
+    apply_action(state, action)
+```
+
+This allows thousands of games to be simulated for testing or AI training.
+
+---
+
+# Architecture
+
+The engine follows a modular architecture:
+
+```
+GameState
+    |
+Action (Draw / Discard / Replace / UsePower / CallKaboom)
+    |
+apply_action()
+    |
+ActionResult
+```
+
+Key components:
+
+```
+kaboom/cards      → card definitions
+kaboom/players    → player state
+kaboom/powers     → power system
+kaboom/game       → turn engine, reactions, validators
+```
+
+This separation keeps game logic independent from any UI layer.
+
+---
+
+# Project Structure
+
+```
+kaboom/
+    cards/
+    players/
+    powers/
+    game/
+        actions.py
+        game_state.py
+        phases.py
+        reaction.py
+        results.py
+        turn.py
+        validators.py
+
+tests/
+```
+
+---
+
+# Testing
+
+The engine includes a full pytest test suite.
+
+Run tests:
+
+```bash
+pytest
+```
+
+Current coverage includes:
+
+* card scoring
+* deck creation
+* player management
+* power mechanics
+* turn actions
+* reaction logic
+* Kaboom endgame rules
+* full game initialization
+
+---
+
+# Future Improvements
+
+Planned enhancements:
+
+* CLI interface
+* graphical UI
+* AI player agents
+* multiplayer networking
+* replay and event logging
+* Gym-compatible environment for reinforcement learning
+
+---
+
+# License
+
+This project is licensed under the MIT License.
+
+---
+
+# Author
+
+[Arnav Ajay](https://github.com/Arnav-Ajay)
+
+---

kaboom_engine-0.1.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+kaboom/__init__.py,sha256=MIJ3vgrE4LzPxrlj6giUTFVPTuAP7lJWZ4DdZMT9i3E,889
+kaboom/exceptions.py,sha256=htzyYT36tTqQghgs82h1bO5dK5Apo8jwqBraQqHPHf0,444
+kaboom/version.py,sha256=fkhLiQPNUlIo5wbs_2WPJs6Ih9c1uarXshsjoVG5pKk,42
+kaboom/cards/__init__.py,sha256=Xkm2z21flg6VJxf6ltFGJNs4hWJamwpnhPqNQNBBNfs,100
+kaboom/cards/card.py,sha256=Nk0MfQqbe8G83wkvD-BkrcF4FAKCiQbCH31MLdsxKS4,912
+kaboom/game/__init__.py,sha256=lLYvOZKf8d5C2-KzD1dRyGhG1dp5ialnAViIt4FRrQo,563
+kaboom/game/actions.py,sha256=nez151girLgpb-0fQ2xGfkUS9-3KR3qnrwAyrO_I2Vw,1126
+kaboom/game/game_state.py,sha256=D4iVTbRuTSBk_597A9SExAjwPFbeeQqHdYv4o7OovJc,3975
+kaboom/game/phases.py,sha256=YUdPPDX1a6nF0PtMhtlm0uAUqQlUZ2ZSjv-jeNMkuiQ,197
+kaboom/game/reaction.py,sha256=rJ5cUGoBdNPnPL1vyvfq9Oqzcw5oNbiQpz8HWBGmjeM,5303
+kaboom/game/results.py,sha256=mtTaO9You5ARMf5CEG3XwMocePk6KHwre2DEjrODXLk,283
+kaboom/game/turn.py,sha256=Yy1tbRlPbX0QOQyCeyLuNxEtD07cBnCXILyNNWqUE7s,6636
+kaboom/game/validators.py,sha256=ZS_gV9CW9L_UIY_DMMrkCthMON820kR2fV61z-FDXVU,523
+kaboom/players/__init__.py,sha256=yVJ7ejKPLxEJ1Q8FjWGoI7zYYN8HnMOjPO9nsXT6eis,80
+kaboom/players/player.py,sha256=GulGPvjDB69TDqprwGFYUW0RRmyhp-RP5t77mvCfPqo,1328
+kaboom/powers/__init__.py,sha256=pm-_grQP0xmO9YwcXug_bj6smYDd8EFqehXHzfFR2hc,324
+kaboom/powers/base.py,sha256=qdIn7iiYvz2G54cUYHP5a0ci7EB4QafNeUmMyOmBXns,383
+kaboom/powers/blind_swap.py,sha256=PgQOGWnAsDrKYLzW8UoOB3dvf2x1Wu3dcE7v51E0BtA,849
+kaboom/powers/registry.py,sha256=wxxrdFahAJIZM8VPrru_Dcq9hA_XhHhj4camKIQrt3A,353
+kaboom/powers/see_and_swap.py,sha256=Mk4s7RrZisZAioV9Uz7qMoD3KXZEDPTEH0ss8qL37Pw,1135
+kaboom/powers/see_other.py,sha256=a2rPOxsWDA2dpWx-TQIiRy8u-7Zm-axl-LJvdY_XVBA,718
+kaboom/powers/see_self.py,sha256=2n06x9P7ISvkZEDvd3XsodJC11KpzFmkHdtikZYZfOQ,617
+kaboom_engine-0.1.0.dist-info/licenses/LICENSE,sha256=cBLtln6E2ziRnpA0_xU0CXiHWh34dNKoQvJufm0b94M,1076
+kaboom_engine-0.1.0.dist-info/METADATA,sha256=nYLhoIOHsGdx_Pzx3WBqMi0AaZhhq5PXR18PstcWtLI,3271
+kaboom_engine-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+kaboom_engine-0.1.0.dist-info/top_level.txt,sha256=HWvUo4xUyc9VDNbhCXca57trgtt3nltDnDBGb0A35Zc,7
+kaboom_engine-0.1.0.dist-info/RECORD,,

kaboom_engine-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

kaboom_engine-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,11 @@
+MIT License
+
+Copyright (c) 2026 Arnav Ajay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kaboom_engine-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+kaboom