PAUK - Spider Solitaire Game

A modern implementation of the classic Spider Solitaire card game built with Python and Pygame.

Overview

PAUK (Russian: "Паук" - Spider) is a single-suit Spider Solitaire game featuring:

• Clean, intuitive drag-and-drop interface
• Automatic sequence completion
• Proper game rule validation
• Modular, well-documented codebase
• Comprehensive logging and error handling

Features

• Complete Spider Solitaire gameplay with all traditional rules
• Drag-and-drop card movement for intuitive play
• Automatic sequence removal when King-to-Ace sequences are completed
• Visual feedback for valid moves and game state
• Keyboard shortcuts for common actions
• Game statistics tracking sequences completed
• Professional codebase with proper separation of concerns

Requirements

• Python 3.9.6 or higher
• Pygame 2.6.1

Installation

Option 1: Quick Setup (Recommended)

1. Clone or download the project
2. Navigate to the project directory:

   cd PAUK

3. Activate the virtual environment (if using the existing one):

   # Windows
   Scripts\activate
   
   # Linux/Mac
   source Scripts/activate

4. Install dependencies:

   pip install -r requirements.txt

Option 2: Fresh Installation

1. Create a new virtual environment:

   python -m venv pauk_env

2. Activate the environment:

   # Windows
   pauk_env\Scripts\activate
   
   # Linux/Mac
   source pauk_env/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

Running the Game

Method 1: Using the launcher (Recommended)

# Make sure you're in the virtual environment
python pauk.py

Method 2: Direct execution

# Make sure you're in the virtual environment first:
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # Linux/Mac

# Then run the game
python src/main.py

Method 3: Using the setup script

python setup.py

Running Tests

Option 1: Using the test runner (Recommended)

python run_tests.py

Option 2: Using unittest directly

# Make sure you're in the virtual environment
python -m unittest discover tests -v

Option 3: Individual test files

python -m unittest tests.test_card -v
python -m unittest tests.test_game_rules -v

How to Play

Objective

Remove all cards from the playing field by creating complete sequences from King to Ace of the same suit.

Rules

1. Card Movement: Only face-up cards can be moved
2. Sequence Building: Cards must be placed in descending order of the same suit
3. Multi-Card Selection: You can move sequences of properly ordered cards together
4. Empty Piles: Any card can be placed on an empty pile
5. Stock: Click "Add Cards" to deal one card to each pile (when stock is available)
6. Auto-Completion: Complete King-to-Ace sequences are automatically removed

Controls

• Mouse: Click and drag to move cards
• Escape: Cancel current selection
• F2: Start new game
• F1: Show help (future feature)

Game Interface

• Stock Counter: Shows remaining cards in stock
• Sequences Counter: Shows completed sequences
• Add Cards Button: Deals cards from stock to all piles

Project Structure

PAUK/
├── src/                          # Main source code
│   ├── main.py                  # Entry point
│   ├── config/                  # Configuration
│   │   ├── constants.py         # Game constants
│   │   └── __init__.py
│   ├── models/                  # Game models
│   │   ├── card.py             # Card class
│   │   ├── pile.py             # Pile class
│   │   └── __init__.py
│   ├── game/                    # Game logic
│   │   ├── engine.py           # Main game engine
│   │   ├── rules.py            # Rule validation
│   │   └── __init__.py
│   ├── ui/                      # User interface
│   │   ├── renderer.py         # Graphics rendering
│   │   ├── events.py           # Event handling
│   │   └── __init__.py
│   └── __init__.py
├── tests/                       # Unit tests (future)
├── requirements.txt             # Dependencies
├── README.md                   # This file
├── PAUK_PROJECT_SPECIFICATION.md # Detailed specification
└── .gitignore                  # Git ignore rules

Development

Code Organization

The codebase follows clean architecture principles:

• Models (src/models/): Core game entities (Card, Pile)
• Game Logic (src/game/): Business rules and game engine
• UI (src/ui/): Rendering and event handling
• Configuration (src/config/): Constants and settings

Logging

The game includes comprehensive logging:

• Console output for real-time feedback
• Log file (pauk_game.log) for debugging
• Different log levels for various components

Error Handling

• Graceful error recovery for invalid moves
• Comprehensive exception handling
• User-friendly error messages

Technical Details

• Language: Python 3.9.6
• Framework: Pygame 2.6.1
• Architecture: Modular object-oriented design
• Window Size: 1000×700 pixels
• Card Size: 70×100 pixels
• Performance: 60 FPS with efficient rendering

Troubleshooting

Common Issues

1. "No module named 'pygame'" Error:

   • Problem: You're running tests/game outside the virtual environment
   • Solution: Activate the virtual environment first:

     # Windows
     .venv\Scripts\activate
     
     # Linux/Mac
     source .venv/bin/activate

   • Alternative: Install pygame globally: pip install pygame==2.6.1
   • Check: Look for (.venv) prefix in your command prompt

2. Import Errors:

   • Ensure virtual environment is activated
   • Check that pygame is installed: pip list | grep pygame

3. Game Won't Start:

   • Verify Python version: python --version
   • Check log file for error details

4. Performance Issues:

   • Close other applications
   • Check system resources

5. Tests Failing:

   • Use python run_tests.py for detailed diagnostics
   • Ensure all dependencies are installed: pip install -r requirements.txt

Getting Help

Check the log file pauk_game.log for detailed error information. The game logs all major actions and errors with timestamps.

Future Enhancements

• Multiple difficulty levels (2-suit, 4-suit variations)
• Save/load game functionality
• Statistics tracking across sessions
• Sound effects and animations
• Online leaderboards
• Undo/redo functionality

Contributing

This is a well-structured codebase suitable for learning and extension. Key areas for contribution:

• Unit tests implementation
• UI/UX improvements
• Additional game variations
• Performance optimizations

License

This project is created for educational and entertainment purposes.

Localization

• English Version (this file)
• Russian Version

---

Enjoy playing PAUK Spider Solitaire!