Blackjack Theory Trainer

A desktop application for learning and practicing basic blackjack strategy. Built with Python and customtkinter, it drills you on the mathematically optimal play for every hand based on the dealer's upcard.

Features

• Interactive practice — dealt random hands, you choose Hit, Stand, Double, or Split
• Instant feedback — every action is evaluated against basic strategy with an explanation
• Scenario tracking — decisions are categorized into hard totals, soft totals, and pairs
• Statistics — track your accuracy and longest correct streak
• Streak notifications — get notified when you lose a streak of 3+
• Visual card display — rendered card images for a realistic feel
• Dark mode UI — easy on the eyes during extended sessions

Tech Stack

• Python 3.10+
• customtkinter — modern, themed tkinter widgets
• Pillow — card image rendering

Getting Started

# Clone the repository
git clone https://git.kampmeierdev.com/kampmeierdev/blackjack-theory-game.git
cd blackjack-theory-game

# Create and activate a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run the application
python main.py

Usage

1. You are dealt two cards (the dealer shows one upcard).
2. Classify your hand and click the correct action.
3. Green feedback = correct play; Red feedback = mistake with an explanation.
4. Click Next Round to continue.
5. Use the Hint button if you are unsure.
6. Close the window to view your final session statistics.

Project Structure

blackjack-theory-game/
├── gui/
│   ├── components/       # UI subcomponents (cards, buttons, hints, stats, notifications)
│   ├── gui.py            # Main GUI application window
│   └── utils.py          # Image loading utilities
├── images/cards/         # Card sprite PNGs
├── blackjack_game.py     # Game state and statistics
├── constants.py          # Suits and ranks
├── game_logic.py         # Card dealing, hand evaluation, basic strategy rules
├── main.py               # Entry point
└── requirements.txt

Basic Strategy Reference

The decisions implemented in this trainer follow standard blackjack basic strategy for a multi-deck game where the dealer stands on soft 17 (S17) and doubling after splitting (DAS) is allowed. Notable rules:

• Hard totals: Stand on 17+, hit on 12–16 vs dealer 7+, double on 11 always
• Soft totals: Double A,6–A,7 vs dealer 3–6; stand on A,8+
• Pairs: Always split Aces and 8s; never split 5s or 10s