Game Collection

A collection of classic arcade games including Snake, Tetris, Arkanoid, and Pac-Man, built with Python and Pygame.

Features

• Snake: Classic snake game with growing mechanics
• Tetris: Block-stacking puzzle game with line clearing
• Arkanoid: Breakout-style game with paddle and ball physics
• Pac-Man: Maze navigation game with dots and ghosts

Installation

From Source

# Clone the repository
git clone <repository-url>
cd game-collection

# Install in development mode
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"

From PyPI

# Standard installation
pip install game-collection

# If you have permission issues on Windows:
pip install game-collection --no-deps --user

Windows Installation

If you encounter permission errors with pygame on Windows, use the automated installer:

# Run the installer
install_game.bat

# Or manual installation
pip install game-collection --no-deps --user

Usage

Command Line

After installation, you can run the game collection using:

# Using the entry point (if PATH is configured)
game-collection

# Using Python module (always works)
python -m game

# Using local file (for development)
python main.py

Troubleshooting

If the game-collection command is not found:

1. Windows: Run setup_path.bat as administrator
2. Alternative: Always use python -m game
3. See: Windows Installation Guide for detailed solutions

Development

# Run the game
make run

# Run tests
make test-unit

# Run tests with coverage
make test-cov

# Check code quality
make quality

# Build executable
make build

# Setup pre-commit hooks
make pre-commit-install

# Run pre-commit on all files
make pre-commit-run

# Check readiness for PyPI publication
make publish-check

# Publish to TestPyPI (for testing)
make publish-test

# Publish to PyPI (requires API token)
make publish

Debug Features

The game includes a debug overlay that can be toggled during gameplay:

• F1: Toggle debug overlay on/off
• F2: Reset FPS history
• F3: Toggle fullscreen mode

The debug overlay shows:

• Real-time FPS and FPS history
• Current game and state
• Mouse position
• Currently pressed keys
• Performance statistics

Configuration

The game uses a configuration system that stores settings in platform-appropriate directories:

• Windows: %LOCALAPPDATA%/hleserg/GameCollection/
• macOS: ~/Library/Application Support/GameCollection/
• Linux: ~/.local/share/GameCollection/

Configuration Files

• config.json: Game settings, controls, audio, and difficulty levels
• scores.json: High scores for all games

Configuration Options

The configuration includes:

• Display: Resolution, fullscreen mode, FPS
• Controls: Key mappings for each game
• Game Settings: Speed, grid size, lives, etc.
• Audio: Volume levels and enable/disable
• Difficulty: Easy, Normal, Hard presets

Development

Project Structure

src/
├── game/
│   ├── __init__.py
│   ├── __main__.py          # Entry point
│   ├── main.py              # Main game loop
│   ├── config.py            # Configuration management
│   ├── config.json          # Default configuration
│   ├── games/               # Game implementations
│   │   ├── base.py          # Base game class
│   │   ├── logic.py         # Pure game logic functions
│   │   ├── snake.py         # Snake game
│   │   ├── tetris.py        # Tetris game
│   │   ├── arkanoid.py      # Arkanoid game
│   │   └── pacman.py        # Pac-Man game
│   └── ui/                  # User interface
│       ├── menu.py          # Main menu
│       └── scores.py        # Score management
tests/                       # Unit tests
docs/                        # Documentation

Testing

The project includes comprehensive unit tests for all game logic:

# Run all tests
python -m pytest tests/

# Run specific test file
python -m pytest tests/test_tetris_logic.py

# Run with coverage
python -m pytest tests/ --cov=src/game/games --cov-report=html

Code Quality

The project uses modern Python tooling:

• Ruff: Fast linting and formatting
• MyPy: Static type checking
• Pytest: Testing framework
• Appdirs: Platform-appropriate data directories

Building Executables

# Build with PyInstaller
make build

# Or manually
pyinstaller --onefile --windowed --name GameCollection src/game/__main__.py

Requirements

• Python 3.10+
• Pygame 2.5.0+
• Appdirs 1.4.4+ (for data directory management)

Development Requirements

• Ruff 0.1.0+ (linting and formatting)
• MyPy 1.8.0+ (type checking)
• Pytest 7.4.0+ (testing)
• PyInstaller 5.13.0+ (executable building)

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run the quality checks: make quality
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Changelog

See CHANGELOG.md for a detailed list of changes.