# 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

```bash
# 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