kaboom-engine 0.1.0__tar.gz

kaboom_engine-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,181 @@
+# 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/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_engine-0.1.0/kaboom/cards/__init__.py

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

kaboom_engine-0.1.0/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_engine-0.1.0/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_engine-0.1.0/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_engine-0.1.0/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_engine-0.1.0/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_engine-0.1.0/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"