♠️ BlackJack Casino AI (Production Ready)

This is a scalable, real-time Blackjack game built with Python, Flask, SocketIO, and Redis. It features an AI opponent with three difficulty levels and is built on a robust architecture designed for production deployment.

This project was initially designed and generated by My-AI and refined through iterative debugging.

✨ Key Features

Real-time Gameplay: Uses WebSocket (Flask-SocketIO) to synchronize game state between the server and clients instantly.

Scalable Session Management: Uses Redis as the session store instead of traditional Flask sessions or in-memory dictionaries. This allows the application to be scaled across multiple processes (e.g., Gunicorn workers) while maintaining user state.

AI Opponent: Play against an AI with three distinct difficulty levels: Easy, Medium, and Hard.

Persistent Balance: Player balances are persistently stored in an SQL database (SQLite/PostgreSQL) via SQLAlchemy.

Asynchronous Task Handling: Uses eventlet to spawn background tasks for AI and Dealer turns, ensuring the player's UI is never blocked.

🛠️ Tech Stack

Backend

Python 3.10+

Flask: Core web application framework.

Flask-SocketIO: Real-time bidirectional communication (WebSocket).

Redis: Scalable session storage for active GameSession objects.

Flask-SQLAlchemy: Persistent storage for user data (e.g., balance).

Eventlet / Gunicorn: Asynchronous WSGI server for production.

python-dotenv: Management of environment variables (from .env).

Frontend

HTML5

CSS3: Custom casino-themed styling

JavaScript (ES6+): Socket.IO client for state-driven UI updates.

📂 Project Structure

blackjack/ ├── game/ # Core game logic package │ ├── init.py (Package initializer, must be empty) │ ├── logic.py (Pure game logic: Card, Deck, Player, GameSession) │ └── routes.py (SocketIO events and HTTP routes) │ ├── static/ # Frontend assets │ ├── style.css │ └── app.js │ ├── templates/ # Flask/Jinja2 templates │ └── index.html │ ├── .env (★ Must be created manually) ├── .env.example (Template for environment variables) ├── .gitignore (Git ignore list) ├── app.py (Flask application factory) ├── config.py (Configuration classes) ├── extensions.py (db, socketio, redis_client instances) ├── models.py (SQLAlchemy User model) ├── requirements.txt (Python dependencies) ├── utils.py (Logging setup, etc.) └── wsgi.py (WSGI entry point for running the server)

🚀 Setup and Launch Guide

1. Prerequisites

Python 3.10 or newer.

Redis Server: Must be installed and running.

(For Windows, using WSL/Ubuntu is recommended: sudo apt install redis-server)

2. Installation

Clone the repository

git clone https://github.com/EMMA019/black-jackgames.git cd black-jackgames

Create and activate a Python virtual environment

python -m venv venv

On Windows

.\venv\Scripts\activate

On macOS / Linux

source venv/bin/activate

Install all required libraries

pip install -r requirements.txt

Set up environment variables Copy the example file to create your local environment file.

On Windows

copy .env.example .env

On macOS / Linux

cp .env.example .env

Now, edit the .env file and set your SECRET_KEY.

Important: If you encounter connection errors (like Lookup timed out on Windows), change the REDIS_URL from localhost to the direct IP address:

.env file

REDIS_URL='redis://127.0.0.1:6379/0'

3. Launching the Application

(Terminal 1) Start your Redis Server If it's not already running, start Redis.

Example for WSL (Ubuntu)

sudo service redis-server start

(Terminal 2) Start the Web Server In the project's root directory (where wsgi.py is located), run the wsgi.py file.

python wsgi.py

You should see the following output if successful:

[INFO] wsgi: Game blueprint registered successfully. [INFO] wsgi: Starting Eventlet WSGI server for local development... [INFO] wsgi: SocketIO server starting on 0.0.0.0:5000 (12345) wsgi starting up on http://0.0.0.0:5000

Open Your Browser Navigate to the following address in your web browser:

http://localhost:5000

(or　http://127.0.0.1:5000)