Pong - Python Edition

A modern, professionally-architected implementation of the classic Pong game using State Pattern, MVC Architecture, and best practices in game development.

✨ Features

• 🎮 Two-Player Local Multiplayer - Classic head-to-head gameplay
• 🎨 Professional Architecture - State Pattern + MVC for clean, maintainable code
• 🏗️ Design Patterns - Singleton, State, Observer, and more
• 📝 Comprehensive Documentation - Fully documented with docstrings and type hints
• ✅ Unit Tested - Tested components ensure reliability
• 🔧 Modular Design - Easy to extend with new features
• 🎯 Separation of Concerns - Models, Views, and Controllers clearly separated

🏛️ Architecture

The project follows professional software engineering practices with a clean MVC architecture and multiple design patterns:

Design Patterns Used

1. State Pattern - Game states (Menu, Playing, Paused, GameOver)
2. MVC Pattern - Separation of Models, Views, and Controllers
3. Singleton Pattern - GameManager as single game instance
4. Observer Pattern - Event-based communication (planned)
5. Strategy Pattern - Pluggable input controllers

Project Structure

game/
├── __init__.py
├── game_manager.py          # Singleton GameManager + main loop
├── game_states.py           # State Pattern implementation
│
├── models/                  # Business Logic Layer
│   ├── __init__.py
│   ├── entities.py         # Ball, Paddle (game entities)
│   └── game_model.py       # PongGameModel (game state)
│
├── views/                   # Presentation Layer
│   ├── __init__.py
│   ├── game_view.py        # Game rendering
│   ├── menu_view.py        # Menu screen
│   └── pause_view.py       # Pause overlay
│
└── controllers/             # Control Layer
    ├── __init__.py
    ├── input_controller.py # Input handling
    └── collision_controller.py  # Collision logic

Architecture Diagram

app.py (Entry Point)
    │
    ├─→ GameManager (Singleton)
    │       ├─→ StateManager
    │       │      ├─→ MenuState
    │       │      ├─→ PlayingState
    │       │      ├─→ PausedState
    │       │      └─→ GameOverState
    │       │
    │       └─→ PlayingState (Active)
    │              ├─→ PongGameModel (Model)
    │              │      ├─→ Ball
    │              │      └─→ Paddle (x2)
    │              │
    │              ├─→ GameView (View)
    │              │
    │              └─→ Controllers
    │                     ├─→ InputController
    │                     └─→ CollisionController

🎮 Controls

Player	Up	Down
Player 1 (Left)	W	S
Player 2 (Right)	↑ Arrow	↓ Arrow

Other Controls:

• ESC - Pause game / Back to menu
• Enter/Space - Select menu option

📋 Requirements

• Python 3.8 or higher
• Pygame 2.5.2
• Colorama 0.4.6

🚀 Installation

Using Virtual Environment (Recommended)

# Clone the repository
git clone https://github.com/userlg/Pong-Python.git
cd Pong-Python

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
# source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run the game
python app.py

Using pip (Global installation)

# Clone the repository
git clone https://github.com/userlg/Pong-Python.git
cd Pong-Python

# Install dependencies
pip install -r requirements.txt

# Run the game
python app.py

Using Docker

# Build the image
docker build -t pong-python .

# Run the container
docker run -it pong-python

🎯 Game Rules

• First player to reach 5 points wins
• Ball speed adjusts based on paddle hit position
• Game enters Game Over state when winner is determined
• Press Space/Enter to play again or ESC for menu

🧪 Testing

Run the test suite:

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest tests/ -v

# Run tests with coverage
pytest tests/ --cov=. --cov-report=html

🛠️ Development

Code Quality Tools

This project uses several tools to maintain code quality:

• Black - Code formatting
• Flake8 - Linting
• MyPy - Type checking
• isort - Import sorting

# Install development dependencies
pip install -r requirements-dev.txt

# Format code
black .

# Run linter
flake8 .

# Type check
mypy .

# Sort imports
isort .

Pre-commit Hooks

Set up pre-commit hooks to automatically check code quality:

# Install pre-commit
pip install pre-commit

# Install git hooks
pre-commit install

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

📸 Screenshots

Gameplay

Scoring

Victory Screen

🤝 Contributing

Contributions are welcome! This project now uses professional design patterns making it easier to add new features:

Easy additions thanks to architecture:

• New game states (Settings, Tutorial, etc.)
• Different game modes
• AI opponents
• Custom themes
• Power-ups and special effects

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Follow the existing architecture patterns
4. Commit your changes (git commit -m 'Add some AmazingFeature')
5. Push to the branch (git push origin feature/AmazingFeature)
6. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Userlg - GitHub Profile

🙏 Acknowledgments

• Classic Pong game by Atari
• Pygame community for excellent documentation
• Design patterns community for architecture guidance
• All contributors who help improve this project

🗺️ Roadmap

• Add AI opponent for single-player mode
• Implement difficulty levels
• Add sound effects and background music
• Create power-ups and special effects
• Add online multiplayer support
• Implement leaderboard system
• Add customizable themes and colors
• Create settings menu with controls remapping

---

📚 Technical Details

Why This Architecture?

State Pattern Benefits:

• Easy to add new game states
• Clear state transitions
• Each state manages its own logic
• Reduced complexity in main loop

MVC Benefits:

• Separation of concerns
• Easier testing
• Reusable components
• Clear data flow

Testability:

• Models can be tested independently
• Views can be mocked
• Controllers have clear interfaces

Performance

• Maintains consistent 60 FPS
• Efficient rendering with cached resources
• Clean resource management
• No memory leaks in state transitions

---

Made with ❤️ and professional design patterns by Userlg

Version 2.0.0 - Professional Architecture Edition