# Games Collection
A comprehensive collection of games implemented in Python, organized by category. The project includes 49 playable games
(15 card games + 21 paper games + 4 dice games + 4 word games + 5 logic games) ranging from casino classics like Texas
Hold'em and Blackjack to strategy games like Checkers and Chess, word puzzles, dice games, and logic challenges.
**📖 See [GAMES.md](GAMES.md) for a complete catalog of all available games.**
## Installation
### From PyPI (Recommended)
The easiest way to install the Games Collection is via pip:
```bash
# Standard installation
pip install games-collection
# With GUI support
pip install games-collection[gui]
# For development
pip install games-collection[dev]
```
After installation, you can run games using the `games-*` commands:
```bash
# Card games
games-poker
games-blackjack
games-uno
games-war
# Paper games
games-tic-tac-toe
games-battleship
games-checkers
# Dice games
games-craps
games-bunco
# See all available games
pip show games-collection
```
### From Source
For development or testing the latest changes:
```bash
git clone https://github.com/saint2706/Games.git
cd Games
# Install in editable mode with development dependencies
pip install -e ".[dev]"
# Run games using Python module syntax
python -m card_games.war
python -m paper_games.tic_tac_toe
```
### Other Options
- **Docker**: See [docs/deployment/DEPLOYMENT.md](docs/deployment/DEPLOYMENT.md#docker-deployment)
- **Standalone Executables**: Download from [Releases](https://github.com/saint2706/Games/releases)
- **Complete Guide**: See [docs/deployment/DEPLOYMENT.md](docs/deployment/DEPLOYMENT.md)
## Repository layout
```text
card_games/
├── common/ # Shared card representations
├── poker/ # Texas Hold'em and Omaha with tournament mode
├── blackjack/ # Casino-style blackjack with splits, doubles, and GUI
├── bluff/ # Cheat/Bluff card game with AI personalities
├── uno/ # Classic Uno with house rules and team mode
├── hearts/ # Trick-taking with shooting the moon
├── spades/ # Partnership bidding with nil bids
├── gin_rummy/ # Two-player melding game
├── bridge/ # Contract bridge with simplified bidding
├── solitaire/ # Klondike patience game
├── cribbage/ # Pegging and crib scoring to 121 points
├── euchre/ # Trump-based trick-taking with bowers
├── rummy500/ # Melding variant with negative scoring
├── go_fish/ # Classic card matching game
├── war/ # Simple comparison card game
└── crazy_eights/ # Discard matching with action cards
paper_games/
├── tic_tac_toe/ # Minimax AI with ultimate variant
├── battleship/ # Naval combat with strategic AI
├── hangman/ # Word guessing with themed categories
├── dots_and_boxes/ # Connect edges to capture boxes
├── nim/ # Mathematical strategy with variants
├── unscramble/ # Word unscrambling with timed mode
├── connect_four/ # Vertical grid with gravity mechanics
├── checkers/ # Jump mechanics with king promotion
├── mancala/ # Stone distribution game
├── othello/ # Disc flipping with positional strategy
├── sudoku/ # Number puzzle with difficulty levels
├── chess/ # Classic chess with move validation
├── backgammon/ # Race game with dice and strategy
├── mastermind/ # Code-breaking deduction game
├── boggle/ # Word search in letter grid
├── pentago/ # Tic-tac-toe with board rotation
├── sprouts/ # Topological connection game
├── snakes_and_ladders/ # Classic board game with dice
├── yahtzee/ # Dice combination scoring game
├── twenty_questions/ # Deductive guessing game
└── four_square_writing/ # Creative writing game
dice_games/
├── farkle/ # Risk-based dice scoring with hot dice
├── craps/ # Casino dice game with betting
├── liars_dice/ # Bluffing game with hidden dice
└── bunco/ # Social dice game with rounds
word_games/
├── trivia/ # Question and answer trivia game
├── crossword/ # Crossword puzzle generation and solving
├── anagrams/ # Word rearrangement challenge
└── wordbuilder/ # Build words from letter sets
logic_games/
├── minesweeper/ # Classic mine detection puzzle
├── lights_out/ # Toggle puzzle with pattern solving
├── sliding_puzzle/ # Number tile sliding game
├── picross/ # Nonogram picture logic puzzle
└── sokoban/ # Warehouse box-pushing puzzle
common/
├── architecture/ # Architectural patterns (plugin, events, persistence)
├── analytics/ # Game analytics and statistics
├── cli_utils.py # Enhanced CLI utilities
└── gui_base.py # Common GUI components
```
## Documentation roadmap
Every game module now opens with an extensive module-level docstring that introduces the contained classes and explains
how they collaborate. Class and function docstrings are deliberately verbose so that you can treat the source as an
executable design document. To dive in:
- Start with `card_games/bluff/bluff.py` for a guided tour of the Cheat/Bluff engine, including commentary on turn
structure and challenge resolution.
- Explore `card_games/poker/poker.py` and `card_games/poker/gui.py` to see how the Texas hold'em mechanics feed into
both a CLI and Tkinter front-end.
- Browse `card_games/bluff/gui.py` to learn how the GUI keeps its widgets in sync with the engine state using richly
annotated helper methods.
Each module's docstrings provide inline references to supporting utilities so you can jump between files without losing
context.
## Paper and pencil classics
Looking for lighter fare? The `paper_games` package recreates a handful of classroom staples:
- `python -m paper_games.hangman` drops you into a word-guessing showdown with configurable mistake limits, gallows art
that fills in piece by piece, and a curated vocabulary sourced from the
[The Hangman Wordlist](https://github.com/TheBiemGamer/The-Hangman-Wordlist) project. Go letter by letter or gamble on
a full-word reveal.
- `python -m paper_games.tic_tac_toe` pits you against a perfect minimax AI that respects coin tosses for the opening
move, supports X-or-O selection, and uses coordinate input (A1 through C3) so the board feels like the
pencil-and-paper classic.
- `python -m paper_games.dots_and_boxes` lets you outline squares on a 2×2 board, while the computer now reads chains,
takes bonus turns, and prints coordinate guides so you can follow along with precision.
- `python -m paper_games.battleship` challenges you to sink a trio of hidden ships spread across a 6×6 ocean.
- `python -m paper_games.unscramble` serves up scrambled words over multiple rounds and keeps score of your successes,
drawing from the same curated word list as hangman for consistency.
- `python -m paper_games.nim` offers a comprehensive exploration of combinatorial game theory with classic Nim plus
variants (Northcott's Game and Wythoff's Game). Features include graphical heap visualization, educational mode with
strategy explanations, multiplayer support (3+ players), and custom rule variations. The optimal AI opponent teaches
winning strategies while you play.
## Blackjack
Take a seat at a richly detailed blackjack table that recreates the flow of a casino shoe. The Tkinter interface renders
premium card art, highlights the active hand, animates the dealer's draw, and keeps your bankroll front and centre while
you decide when to hit, stand, double, or split.
```bash
python -m card_games.blackjack
```
Prefer the original text-mode experience? Launch it with:
```bash
python -m card_games.blackjack --cli --bankroll 300 --min-bet 15 --decks 4
```
Highlights:
- Shoe management with automatic shuffling as the cards run low.
- Animated dealer reveals, natural blackjack detection, and soft-17 behaviour.
- Support for doubling down, splitting pairs, and per-hand outcome summaries that update your bankroll instantly in both
the GUI and CLI.
## Poker
Sit at a four-player poker table and battle three computer-controlled opponents across full betting rounds. Each
difficulty level tunes the bots' Monte Carlo-backed decision making—higher settings reduce mistakes, tighten the hands
they play, and increase their aggression when they sense strength.
The poker module now supports multiple game variants, betting structures, and tournament play with comprehensive
statistics tracking.
```bash
# Classic Texas Hold'em
python -m card_games.poker --difficulty Medium --rounds 5 --seed 123
# Omaha Hold'em with 4 hole cards
python -m card_games.poker --variant omaha --rounds 5
# Tournament mode with increasing blinds
python -m card_games.poker --tournament --rounds 10
# Pot-limit betting
python -m card_games.poker --limit pot-limit --rounds 5
```
Gameplay features:
- **Game Variants**: Texas Hold'em (2 hole cards) and Omaha (4 hole cards with exact 2+3 hand evaluation)
- **Betting Limits**: No-limit, pot-limit, and fixed-limit structures
- **Tournament Mode**: Blinds increase automatically based on configurable schedule
- **Statistics Tracking**: Hands won, fold frequency, showdown performance, and net profit tracked for all players
- **Hand History**: Complete game logs saved to JSON files for post-session review
- **Showdown Animations**: Visual card reveals and hand ranking explanations in GUI
- Rotating dealer button with blinds, betting rounds (pre-flop through river), and side-pot aware chip accounting
- Skill profiles that estimate equity against unknown hands to guide calls, bluffs, and value raises
- Detailed action narration in the CLI plus a live-updating graphical table for players who prefer a visual experience
Launch the GUI to play the same match with card visuals, action buttons, and a running log of the hand:
```bash
python -m card_games.poker --gui --difficulty Hard --rounds 3
python -m card_games.poker --gui --variant omaha --tournament
```
Evaluate an arbitrary set of cards via the helper utility:
```bash
python -m card_games.poker.poker_hand_evaluator As Kd Qh Jc Tc
```
## Bluff
Play a full game of Cheat/Bluff where every participant—bots included—handles a hand of cards. Each turn a player
discards a card face down and claims its rank. If the claim is challenged, the entire pile swings to the truthful
player; otherwise it keeps growing until someone is caught. First to shed every card, or whoever holds the fewest cards
after the configured number of table rotations, wins the match.
Difficulty levels tune the number of opponents, deck count, and AI personalities:
| Difficulty | Bots | Decks | Personality |
| ---------- | ---- | ----- | --------------------------------------------- |
| Noob | 1 | 1 | Cautious, rarely bluffs |
| Easy | 2 | 1 | Even tempered with light deception |
| Medium | 2 | 2 | Balanced mix of bluffing and scrutiny |
| Hard | 3 | 2 | Bolder bluffs and sharper challenges |
| Insane | 4 | 3 | Aggressive liars who constantly police rivals |
Fire up a five-rotation match on the default "Noob" setting from the terminal:
```bash
python -m card_games.bluff
```
Add variety with seeds, longer tables, or the graphical interface:
```bash
python -m card_games.bluff --difficulty Hard --rounds 7 --seed 42
python -m card_games.bluff --gui --difficulty Medium
```
### Gameplay highlights
- Bots manage full hands, weigh whether to lie based on the pot size, and keep memory of who was recently caught
stretching the truth.
- Suspicion travels around the table. Other bots (and you) can challenge any claim, so expect lively AI-versus-AI
skirmishes when a rival seems shady.
- The Tkinter interface offers card buttons, challenge controls, and a running event log alongside live card counts for
every player.
## Uno
Enjoy a fast-paced game of Uno that recreates the classic 108-card deck, supports stacking draw cards, and lets you
battle an assortment of AI personalities. The rebuilt engine adds authentic Wild +4 challenges, automatic penalties when
someone forgets to shout UNO, and smarter bots that weigh risks before bluffing with a draw card. The terminal interface
highlights the active colour, tracks draw penalties, and prompts for wild-card colour selections while bots
automatically choose colours based on the makeup of their hands.
```bash
python -m card_games.uno --players 4 --bots 3 --bot-skill balanced --seed 2024
```
Highlights:
- Authentic card distribution with skips, reverses, draw-twos, and wild draw fours that support stacking and optional
challenges when a rival might be bluffing.
- Adjustable bot aggression so you can face easy-going opponents or relentless action-card junkies that decide when to
risk a Wild +4 challenge.
- Automatic UNO call enforcement: fail to declare in time and the table hands you a two-card penalty.
- Launch `python -m card_games.uno --gui` to enjoy a Tkinter interface with colour-coded cards, UNO toggles, penalty
prompts, and a scrolling event log that mirrors each turn.
## Development and Code Quality
This project follows high code quality standards with automated tooling:
### For Contributors
- **Base Classes:** Common game engine and GUI interfaces in `common/` module
- **AI Strategies:** Reusable AI patterns for computer opponents
- **Pre-commit Hooks:** Automated code formatting and linting
- **Type Hints:** Comprehensive type annotations throughout
- **Testing:** 90%+ test coverage target with pytest
- **Complexity Analysis:** Code complexity monitoring and enforcement
### Documentation
- **[GAMES.md](GAMES.md)** - Complete catalog of all available games
- **[docs/architecture/ARCHITECTURE.md](docs/architecture/ARCHITECTURE.md)** - Architecture patterns and base class
usage
- **[docs/development/CODE_QUALITY.md](docs/development/CODE_QUALITY.md)** - Code standards, tools, and guidelines
- **[docs/development/TESTING.md](docs/development/TESTING.md)** - Testing guide and best practices
- **[docs/development/IMPLEMENTATION_NOTES.md](docs/development/IMPLEMENTATION_NOTES.md)** - Detailed implementation
notes
- **[docs/planning/TODO.md](docs/planning/TODO.md)** - Roadmap and future plans
- **[common/README.md](common/README.md)** - Common module documentation
- **[examples/](examples/)** - Example implementations using base classes
### Quick Start for Development
```bash
# Install the package in editable mode with development dependencies
pip install -e ".[dev]"
# Or install from PyPI for testing
pip install games-collection[dev]
# Install pre-commit hooks
pre-commit install
# Run the full test suite (includes performance benchmarks)
pytest
# Run a quicker subset that skips performance benchmarks
pytest -m "not performance"
# Check code quality
pre-commit run --all-files
./scripts/check_complexity.sh
# Run GitHub Actions workflows locally (requires Docker)
make setup-act # Install act for local workflow testing
make workflow-ci # Test CI workflow locally
make workflow-list # List all workflows
```
See [docs/development/CODE_QUALITY.md](docs/development/CODE_QUALITY.md) for detailed guidelines.
### Testing Workflows Locally
You can run and debug GitHub Actions workflows locally before pushing to GitHub:
```bash
# Install act (GitHub Actions local runner)
./scripts/setup_act.sh
# Run the CI workflow locally
./scripts/run_workflow.sh ci
# Run specific jobs
./scripts/run_workflow.sh ci --job lint
./scripts/run_workflow.sh ci --job test
# List all available workflows
./scripts/run_workflow.sh all
```
This allows you to:
- Test workflow changes without pushing to GitHub
- Debug failed jobs locally with faster iteration
- Save CI/CD minutes by testing locally first
- Work offline while developing workflows
See [docs/development/LOCAL_WORKFLOWS.md](docs/development/LOCAL_WORKFLOWS.md) for complete documentation.
Raw data
{
"_id": null,
"home_page": null,
"name": "games-collection",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "saint2706 <45678566+saint2706@users.noreply.github.com>",
"keywords": "games, card-games, board-games, uno, poker, blackjack, tic-tac-toe, chess, ai, gui, cli",
"author": null,
"author_email": "saint2706 <45678566+saint2706@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/bc/23/213eef50efcd9a492b55796eee86ca4573ef82092ab1ea8a350aa3d1225d/games_collection-1.0.0.tar.gz",
"platform": null,
"description": "# Games Collection\n\nA comprehensive collection of games implemented in Python, organized by category. The project includes 49 playable games\n(15 card games + 21 paper games + 4 dice games + 4 word games + 5 logic games) ranging from casino classics like Texas\nHold'em and Blackjack to strategy games like Checkers and Chess, word puzzles, dice games, and logic challenges.\n\n**\ud83d\udcd6 See [GAMES.md](GAMES.md) for a complete catalog of all available games.**\n\n## Installation\n\n### From PyPI (Recommended)\n\nThe easiest way to install the Games Collection is via pip:\n\n```bash\n# Standard installation\npip install games-collection\n\n# With GUI support\npip install games-collection[gui]\n\n# For development\npip install games-collection[dev]\n```\n\nAfter installation, you can run games using the `games-*` commands:\n\n```bash\n# Card games\ngames-poker\ngames-blackjack\ngames-uno\ngames-war\n\n# Paper games\ngames-tic-tac-toe\ngames-battleship\ngames-checkers\n\n# Dice games\ngames-craps\ngames-bunco\n\n# See all available games\npip show games-collection\n```\n\n### From Source\n\nFor development or testing the latest changes:\n\n```bash\ngit clone https://github.com/saint2706/Games.git\ncd Games\n\n# Install in editable mode with development dependencies\npip install -e \".[dev]\"\n\n# Run games using Python module syntax\npython -m card_games.war\npython -m paper_games.tic_tac_toe\n```\n\n### Other Options\n\n- **Docker**: See [docs/deployment/DEPLOYMENT.md](docs/deployment/DEPLOYMENT.md#docker-deployment)\n- **Standalone Executables**: Download from [Releases](https://github.com/saint2706/Games/releases)\n- **Complete Guide**: See [docs/deployment/DEPLOYMENT.md](docs/deployment/DEPLOYMENT.md)\n\n## Repository layout\n\n```text\ncard_games/\n\u251c\u2500\u2500 common/ # Shared card representations\n\u251c\u2500\u2500 poker/ # Texas Hold'em and Omaha with tournament mode\n\u251c\u2500\u2500 blackjack/ # Casino-style blackjack with splits, doubles, and GUI\n\u251c\u2500\u2500 bluff/ # Cheat/Bluff card game with AI personalities\n\u251c\u2500\u2500 uno/ # Classic Uno with house rules and team mode\n\u251c\u2500\u2500 hearts/ # Trick-taking with shooting the moon\n\u251c\u2500\u2500 spades/ # Partnership bidding with nil bids\n\u251c\u2500\u2500 gin_rummy/ # Two-player melding game\n\u251c\u2500\u2500 bridge/ # Contract bridge with simplified bidding\n\u251c\u2500\u2500 solitaire/ # Klondike patience game\n\u251c\u2500\u2500 cribbage/ # Pegging and crib scoring to 121 points\n\u251c\u2500\u2500 euchre/ # Trump-based trick-taking with bowers\n\u251c\u2500\u2500 rummy500/ # Melding variant with negative scoring\n\u251c\u2500\u2500 go_fish/ # Classic card matching game\n\u251c\u2500\u2500 war/ # Simple comparison card game\n\u2514\u2500\u2500 crazy_eights/ # Discard matching with action cards\npaper_games/\n\u251c\u2500\u2500 tic_tac_toe/ # Minimax AI with ultimate variant\n\u251c\u2500\u2500 battleship/ # Naval combat with strategic AI\n\u251c\u2500\u2500 hangman/ # Word guessing with themed categories\n\u251c\u2500\u2500 dots_and_boxes/ # Connect edges to capture boxes\n\u251c\u2500\u2500 nim/ # Mathematical strategy with variants\n\u251c\u2500\u2500 unscramble/ # Word unscrambling with timed mode\n\u251c\u2500\u2500 connect_four/ # Vertical grid with gravity mechanics\n\u251c\u2500\u2500 checkers/ # Jump mechanics with king promotion\n\u251c\u2500\u2500 mancala/ # Stone distribution game\n\u251c\u2500\u2500 othello/ # Disc flipping with positional strategy\n\u251c\u2500\u2500 sudoku/ # Number puzzle with difficulty levels\n\u251c\u2500\u2500 chess/ # Classic chess with move validation\n\u251c\u2500\u2500 backgammon/ # Race game with dice and strategy\n\u251c\u2500\u2500 mastermind/ # Code-breaking deduction game\n\u251c\u2500\u2500 boggle/ # Word search in letter grid\n\u251c\u2500\u2500 pentago/ # Tic-tac-toe with board rotation\n\u251c\u2500\u2500 sprouts/ # Topological connection game\n\u251c\u2500\u2500 snakes_and_ladders/ # Classic board game with dice\n\u251c\u2500\u2500 yahtzee/ # Dice combination scoring game\n\u251c\u2500\u2500 twenty_questions/ # Deductive guessing game\n\u2514\u2500\u2500 four_square_writing/ # Creative writing game\ndice_games/\n\u251c\u2500\u2500 farkle/ # Risk-based dice scoring with hot dice\n\u251c\u2500\u2500 craps/ # Casino dice game with betting\n\u251c\u2500\u2500 liars_dice/ # Bluffing game with hidden dice\n\u2514\u2500\u2500 bunco/ # Social dice game with rounds\nword_games/\n\u251c\u2500\u2500 trivia/ # Question and answer trivia game\n\u251c\u2500\u2500 crossword/ # Crossword puzzle generation and solving\n\u251c\u2500\u2500 anagrams/ # Word rearrangement challenge\n\u2514\u2500\u2500 wordbuilder/ # Build words from letter sets\nlogic_games/\n\u251c\u2500\u2500 minesweeper/ # Classic mine detection puzzle\n\u251c\u2500\u2500 lights_out/ # Toggle puzzle with pattern solving\n\u251c\u2500\u2500 sliding_puzzle/ # Number tile sliding game\n\u251c\u2500\u2500 picross/ # Nonogram picture logic puzzle\n\u2514\u2500\u2500 sokoban/ # Warehouse box-pushing puzzle\ncommon/\n\u251c\u2500\u2500 architecture/ # Architectural patterns (plugin, events, persistence)\n\u251c\u2500\u2500 analytics/ # Game analytics and statistics\n\u251c\u2500\u2500 cli_utils.py # Enhanced CLI utilities\n\u2514\u2500\u2500 gui_base.py # Common GUI components\n```\n\n## Documentation roadmap\n\nEvery game module now opens with an extensive module-level docstring that introduces the contained classes and explains\nhow they collaborate. Class and function docstrings are deliberately verbose so that you can treat the source as an\nexecutable design document. To dive in:\n\n- Start with `card_games/bluff/bluff.py` for a guided tour of the Cheat/Bluff engine, including commentary on turn\n structure and challenge resolution.\n- Explore `card_games/poker/poker.py` and `card_games/poker/gui.py` to see how the Texas hold'em mechanics feed into\n both a CLI and Tkinter front-end.\n- Browse `card_games/bluff/gui.py` to learn how the GUI keeps its widgets in sync with the engine state using richly\n annotated helper methods.\n\nEach module's docstrings provide inline references to supporting utilities so you can jump between files without losing\ncontext.\n\n## Paper and pencil classics\n\nLooking for lighter fare? The `paper_games` package recreates a handful of classroom staples:\n\n- `python -m paper_games.hangman` drops you into a word-guessing showdown with configurable mistake limits, gallows art\n that fills in piece by piece, and a curated vocabulary sourced from the\n [The Hangman Wordlist](https://github.com/TheBiemGamer/The-Hangman-Wordlist) project. Go letter by letter or gamble on\n a full-word reveal.\n- `python -m paper_games.tic_tac_toe` pits you against a perfect minimax AI that respects coin tosses for the opening\n move, supports X-or-O selection, and uses coordinate input (A1 through C3) so the board feels like the\n pencil-and-paper classic.\n- `python -m paper_games.dots_and_boxes` lets you outline squares on a 2\u00d72 board, while the computer now reads chains,\n takes bonus turns, and prints coordinate guides so you can follow along with precision.\n- `python -m paper_games.battleship` challenges you to sink a trio of hidden ships spread across a 6\u00d76 ocean.\n- `python -m paper_games.unscramble` serves up scrambled words over multiple rounds and keeps score of your successes,\n drawing from the same curated word list as hangman for consistency.\n- `python -m paper_games.nim` offers a comprehensive exploration of combinatorial game theory with classic Nim plus\n variants (Northcott's Game and Wythoff's Game). Features include graphical heap visualization, educational mode with\n strategy explanations, multiplayer support (3+ players), and custom rule variations. The optimal AI opponent teaches\n winning strategies while you play.\n\n## Blackjack\n\nTake a seat at a richly detailed blackjack table that recreates the flow of a casino shoe. The Tkinter interface renders\npremium card art, highlights the active hand, animates the dealer's draw, and keeps your bankroll front and centre while\nyou decide when to hit, stand, double, or split.\n\n```bash\npython -m card_games.blackjack\n```\n\nPrefer the original text-mode experience? Launch it with:\n\n```bash\npython -m card_games.blackjack --cli --bankroll 300 --min-bet 15 --decks 4\n```\n\nHighlights:\n\n- Shoe management with automatic shuffling as the cards run low.\n- Animated dealer reveals, natural blackjack detection, and soft-17 behaviour.\n- Support for doubling down, splitting pairs, and per-hand outcome summaries that update your bankroll instantly in both\n the GUI and CLI.\n\n## Poker\n\nSit at a four-player poker table and battle three computer-controlled opponents across full betting rounds. Each\ndifficulty level tunes the bots' Monte Carlo-backed decision making\u2014higher settings reduce mistakes, tighten the hands\nthey play, and increase their aggression when they sense strength.\n\nThe poker module now supports multiple game variants, betting structures, and tournament play with comprehensive\nstatistics tracking.\n\n```bash\n# Classic Texas Hold'em\npython -m card_games.poker --difficulty Medium --rounds 5 --seed 123\n\n# Omaha Hold'em with 4 hole cards\npython -m card_games.poker --variant omaha --rounds 5\n\n# Tournament mode with increasing blinds\npython -m card_games.poker --tournament --rounds 10\n\n# Pot-limit betting\npython -m card_games.poker --limit pot-limit --rounds 5\n```\n\nGameplay features:\n\n- **Game Variants**: Texas Hold'em (2 hole cards) and Omaha (4 hole cards with exact 2+3 hand evaluation)\n- **Betting Limits**: No-limit, pot-limit, and fixed-limit structures\n- **Tournament Mode**: Blinds increase automatically based on configurable schedule\n- **Statistics Tracking**: Hands won, fold frequency, showdown performance, and net profit tracked for all players\n- **Hand History**: Complete game logs saved to JSON files for post-session review\n- **Showdown Animations**: Visual card reveals and hand ranking explanations in GUI\n- Rotating dealer button with blinds, betting rounds (pre-flop through river), and side-pot aware chip accounting\n- Skill profiles that estimate equity against unknown hands to guide calls, bluffs, and value raises\n- Detailed action narration in the CLI plus a live-updating graphical table for players who prefer a visual experience\n\nLaunch the GUI to play the same match with card visuals, action buttons, and a running log of the hand:\n\n```bash\npython -m card_games.poker --gui --difficulty Hard --rounds 3\npython -m card_games.poker --gui --variant omaha --tournament\n```\n\nEvaluate an arbitrary set of cards via the helper utility:\n\n```bash\npython -m card_games.poker.poker_hand_evaluator As Kd Qh Jc Tc\n```\n\n## Bluff\n\nPlay a full game of Cheat/Bluff where every participant\u2014bots included\u2014handles a hand of cards. Each turn a player\ndiscards a card face down and claims its rank. If the claim is challenged, the entire pile swings to the truthful\nplayer; otherwise it keeps growing until someone is caught. First to shed every card, or whoever holds the fewest cards\nafter the configured number of table rotations, wins the match.\n\nDifficulty levels tune the number of opponents, deck count, and AI personalities:\n\n| Difficulty | Bots | Decks | Personality |\n| ---------- | ---- | ----- | --------------------------------------------- |\n| Noob | 1 | 1 | Cautious, rarely bluffs |\n| Easy | 2 | 1 | Even tempered with light deception |\n| Medium | 2 | 2 | Balanced mix of bluffing and scrutiny |\n| Hard | 3 | 2 | Bolder bluffs and sharper challenges |\n| Insane | 4 | 3 | Aggressive liars who constantly police rivals |\n\nFire up a five-rotation match on the default \"Noob\" setting from the terminal:\n\n```bash\npython -m card_games.bluff\n```\n\nAdd variety with seeds, longer tables, or the graphical interface:\n\n```bash\npython -m card_games.bluff --difficulty Hard --rounds 7 --seed 42\npython -m card_games.bluff --gui --difficulty Medium\n```\n\n### Gameplay highlights\n\n- Bots manage full hands, weigh whether to lie based on the pot size, and keep memory of who was recently caught\n stretching the truth.\n- Suspicion travels around the table. Other bots (and you) can challenge any claim, so expect lively AI-versus-AI\n skirmishes when a rival seems shady.\n- The Tkinter interface offers card buttons, challenge controls, and a running event log alongside live card counts for\n every player.\n\n## Uno\n\nEnjoy a fast-paced game of Uno that recreates the classic 108-card deck, supports stacking draw cards, and lets you\nbattle an assortment of AI personalities. The rebuilt engine adds authentic Wild +4 challenges, automatic penalties when\nsomeone forgets to shout UNO, and smarter bots that weigh risks before bluffing with a draw card. The terminal interface\nhighlights the active colour, tracks draw penalties, and prompts for wild-card colour selections while bots\nautomatically choose colours based on the makeup of their hands.\n\n```bash\npython -m card_games.uno --players 4 --bots 3 --bot-skill balanced --seed 2024\n```\n\nHighlights:\n\n- Authentic card distribution with skips, reverses, draw-twos, and wild draw fours that support stacking and optional\n challenges when a rival might be bluffing.\n- Adjustable bot aggression so you can face easy-going opponents or relentless action-card junkies that decide when to\n risk a Wild +4 challenge.\n- Automatic UNO call enforcement: fail to declare in time and the table hands you a two-card penalty.\n- Launch `python -m card_games.uno --gui` to enjoy a Tkinter interface with colour-coded cards, UNO toggles, penalty\n prompts, and a scrolling event log that mirrors each turn.\n\n## Development and Code Quality\n\nThis project follows high code quality standards with automated tooling:\n\n### For Contributors\n\n- **Base Classes:** Common game engine and GUI interfaces in `common/` module\n- **AI Strategies:** Reusable AI patterns for computer opponents\n- **Pre-commit Hooks:** Automated code formatting and linting\n- **Type Hints:** Comprehensive type annotations throughout\n- **Testing:** 90%+ test coverage target with pytest\n- **Complexity Analysis:** Code complexity monitoring and enforcement\n\n### Documentation\n\n- **[GAMES.md](GAMES.md)** - Complete catalog of all available games\n- **[docs/architecture/ARCHITECTURE.md](docs/architecture/ARCHITECTURE.md)** - Architecture patterns and base class\n usage\n- **[docs/development/CODE_QUALITY.md](docs/development/CODE_QUALITY.md)** - Code standards, tools, and guidelines\n- **[docs/development/TESTING.md](docs/development/TESTING.md)** - Testing guide and best practices\n- **[docs/development/IMPLEMENTATION_NOTES.md](docs/development/IMPLEMENTATION_NOTES.md)** - Detailed implementation\n notes\n- **[docs/planning/TODO.md](docs/planning/TODO.md)** - Roadmap and future plans\n- **[common/README.md](common/README.md)** - Common module documentation\n- **[examples/](examples/)** - Example implementations using base classes\n\n### Quick Start for Development\n\n```bash\n# Install the package in editable mode with development dependencies\npip install -e \".[dev]\"\n\n# Or install from PyPI for testing\npip install games-collection[dev]\n\n# Install pre-commit hooks\npre-commit install\n\n# Run the full test suite (includes performance benchmarks)\npytest\n\n# Run a quicker subset that skips performance benchmarks\npytest -m \"not performance\"\n\n# Check code quality\npre-commit run --all-files\n./scripts/check_complexity.sh\n\n# Run GitHub Actions workflows locally (requires Docker)\nmake setup-act # Install act for local workflow testing\nmake workflow-ci # Test CI workflow locally\nmake workflow-list # List all workflows\n```\n\nSee [docs/development/CODE_QUALITY.md](docs/development/CODE_QUALITY.md) for detailed guidelines.\n\n### Testing Workflows Locally\n\nYou can run and debug GitHub Actions workflows locally before pushing to GitHub:\n\n```bash\n# Install act (GitHub Actions local runner)\n./scripts/setup_act.sh\n\n# Run the CI workflow locally\n./scripts/run_workflow.sh ci\n\n# Run specific jobs\n./scripts/run_workflow.sh ci --job lint\n./scripts/run_workflow.sh ci --job test\n\n# List all available workflows\n./scripts/run_workflow.sh all\n```\n\nThis allows you to:\n\n- Test workflow changes without pushing to GitHub\n- Debug failed jobs locally with faster iteration\n- Save CI/CD minutes by testing locally first\n- Work offline while developing workflows\n\nSee [docs/development/LOCAL_WORKFLOWS.md](docs/development/LOCAL_WORKFLOWS.md) for complete documentation.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A comprehensive collection of classic card, paper, dice, logic, and word games with AI opponents and both CLI and GUI interfaces",
"version": "1.0.0",
"project_urls": {
"Changelog": "https://github.com/saint2706/Games/blob/master/CHANGELOG.md",
"Documentation": "https://github.com/saint2706/Games#readme",
"Homepage": "https://github.com/saint2706/Games",
"Issues": "https://github.com/saint2706/Games/issues",
"Repository": "https://github.com/saint2706/Games"
},
"split_keywords": [
"games",
" card-games",
" board-games",
" uno",
" poker",
" blackjack",
" tic-tac-toe",
" chess",
" ai",
" gui",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c2bf7dba550a89730c5f99f9e40c28b564f210a0c36cce3d83ae851058221fa6",
"md5": "d2252e937a0dfa3854d3138ebb577383",
"sha256": "4c87f3f0f448173c38e027b924c8f33bce43fad5599a0b2aa8f0b024313888fa"
},
"downloads": -1,
"filename": "games_collection-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d2252e937a0dfa3854d3138ebb577383",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 563820,
"upload_time": "2025-10-14T08:31:01",
"upload_time_iso_8601": "2025-10-14T08:31:01.857028Z",
"url": "https://files.pythonhosted.org/packages/c2/bf/7dba550a89730c5f99f9e40c28b564f210a0c36cce3d83ae851058221fa6/games_collection-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bc23213eef50efcd9a492b55796eee86ca4573ef82092ab1ea8a350aa3d1225d",
"md5": "433ad5aca256172e0729864c778ecc79",
"sha256": "d62aafc21a06dae2d2d2452eefbe65832d93faee45f284ed28b8e85bb6ff10e0"
},
"downloads": -1,
"filename": "games_collection-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "433ad5aca256172e0729864c778ecc79",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 647317,
"upload_time": "2025-10-14T08:31:03",
"upload_time_iso_8601": "2025-10-14T08:31:03.657785Z",
"url": "https://files.pythonhosted.org/packages/bc/23/213eef50efcd9a492b55796eee86ca4573ef82092ab1ea8a350aa3d1225d/games_collection-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-14 08:31:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "saint2706",
"github_project": "Games",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "colorama",
"specs": [
[
">=",
"0.4.6"
]
]
}
],
"lcname": "games-collection"
}
JSON
