Kaboom Engine

kaboom-engine is the deterministic rules engine for the Kaboom card game.

Current release line: 0.3.x

It is intended to be reused by:

• CLIs
• simulations and AI agents
• multiplayer servers
• future graphical clients
• development inspection tools

Live prototype client:

• Streamlit prototype: https://kaboom.streamlit.app/

What The Engine Owns

The engine is the source of truth for:

• game setup and dealing
• mandatory opening peek setup
• legal action generation
• turn and reaction phase transitions
• card powers
• Kaboom endgame flow
• player memory mutation when cards move

Interfaces should choose and render actions, not reimplement rules.

What's New In 0.3.0

0.3.0 is the first fully rule-shaped engine release.

Highlights:

• opening peek is now an explicit setup phase instead of an implicit side effect
• power use is discard-first and shares the same contested discard window as reactions
• pending power resolution is explicit through ResolvePendingPower
• reactions are single-card claims, and the initiator may compete for the same discard event
• wrong reaction guesses now reveal information, apply penalty, and keep the window open
• Kaboom final-round discard windows fully resolve before the game ends
• result metadata is richer for CLI, simulation, and future multiplayer/server layers

0.3.1 Patch Notes

Patch updates made after the 0.3.0 line:

• memory updates were tightened for replace, swap, and removal flows
• pending-power target cards are locked while the power is still in motion
• discard-window behavior was tightened around Kaboom final-round resolution
• wrong-reaction penalty defaults were simplified back to one failed attempt per player per discard event
• deck draws now consistently reshuffle from discard through shared draw helpers when needed
• docs and regression coverage were expanded around reaction, power, and memory edge cases

Install

pip install kaboom-engine

Local editable install:

git clone https://github.com/Arnav-Ajay/kaboom-core.git
cd kaboom-core
pip install -e .

Minimal Usage

from kaboom import GameEngine, get_valid_actions, apply_action

engine = GameEngine(game_id=0, num_players=2, hand_size=4)
state = engine.state

while not engine.is_game_over():
    actions = get_valid_actions(state)
    action = actions[0]
    apply_action(state, action)

Note:

• a fresh game starts in the opening peek setup phase
• get_valid_actions(state) already exposes the required OpeningPeek actions before round 1 begins

Docs

Reference docs live in docs/:

• GAME_RULES.md
• ENGINE_FLOW.md
• GAME_ENGINE_API.md

These documents describe:

• state and phase flow
• action dispatch
• memory invariants
• GameEngine methods
• parameters and return types
• ownership boundaries between engine and UI

Related Projects

• kaboom-cli for terminal-based engine debugging
• kaboom-streamlit-prototype for a browser-based development inspector and human-vs-agent prototype
• Live Streamlit deployment: https://kaboom.streamlit.app/

Examples

Two maintained examples live in examples/:

• game_info_demo.py for inspecting setup, memory, and legal actions
• random_policy_simulation.py for a simple simulation / AI / RL-style rollout loop

Architecture

Core modules:

• kaboom/game
• kaboom/powers
• kaboom/players
• kaboom/cards

Main entrypoints:

• GameEngine
• GameState
• apply_action(state, action)
• get_valid_actions(state)

Testing

Run the test suite with:

pytest

Important test coverage areas:

• setup and dealing
• powers
• reactions
• turn flow
• Kaboom endgame
• memory updates after card movement

License

MIT