Whirley Bird

Table of Contents

• Whirley Bird
  • Table of Contents
  • Introduction
  • Core Features
  • Technology Stack
  • Setup and Installation
    • 1. Prerequisites
    • 2. Clone the Repository
    • 3. Create a Virtual Environment (Recommended)
    • 4. Install Dependencies
  • How to Play
  • Project Structure
  • Contributing
  • License
  • Acknowledgements

Introduction

Whirley Bird is an immersive and interactive 2D arcade game where you guide a bird through a sky filled with descending obstacles and collectible apples. What makes this game unique is its control system: your own hand! Using your computer's webcam, the game leverages Google's MediaPipe framework to track your hand's position in real-time, allowing you to intuitively steer the bird left and right.

The goal is simple: collect as many apples as you can to increase your score while skillfully dodging the blocks. As your score climbs, the game's speed increases, offering a progressive challenge. Your high score is saved locally, so you can always come back to beat your personal best.

Core Features

• Gesture-Based Control: Ditch the keyboard and mouse! Control the bird's horizontal movement by simply moving your hand in front of your webcam.
• Real-time Hand Tracking: Utilizes the robust MediaPipe Hands solution for fast and accurate landmark detection, providing a smooth and responsive control experience.
• Dynamic Gameplay: The objective is to dodge falling blocks and collect apples. The simple mechanics are easy to learn but hard to master.
• Progressive Difficulty: The game gets faster every 10 points you score, ensuring the challenge scales with your skill level.
• Persistent High Score: Your highest score is automatically saved to a local SQLite database, so you can track your personal best across sessions.
• Multiple Game Screens: A complete experience with a welcome menu, an in-game UI, a pause screen, and a game-over screen.
• Engaging Audio-Visuals: Features custom assets for backgrounds, sprites, and buttons, along with sound effects for menu interactions, scoring, and game events.

Technology Stack

This project is built using a combination of powerful open-source libraries:

• Game Engine: Pygame for rendering graphics, handling game loops, processing user input (mouse clicks), and managing audio.
• Computer Vision: OpenCV (cv2) for capturing and processing the video feed from the webcam.
• Hand Tracking: Google MediaPipe for its high-fidelity hand and finger tracking solution to translate hand motion into game controls.
• Database: SQLite3 (standard in Python) for lightweight, serverless local database management to store the high score.

Setup and Installation

Follow these steps to get the game running on your local machine.

1. Prerequisites

• Python 3.7 or newer.
• A webcam connected to your computer.

2. Clone the Repository

git clone https://github.com/Qamar2315/Whirleybird.git
cd Whirleybird

3. Create a Virtual Environment (Recommended)

It's good practice to create a virtual environment to keep project dependencies isolated.

# For Windows
python -m venv venv
venv\Scripts\activate

# For macOS/Linux
python3 -m venv venv
source venv/bin/activate

4. Install Dependencies

Install all the required Python libraries using pip.

pip install pygame opencv-python mediapipe

How to Play

1. Run the Game: Execute the main script from your terminal:

   python main.py

2. Initial Setup:

   • A Pygame window will open with the game's welcome screen.
   • A second window from OpenCV will also appear, showing your webcam feed with the hand tracking overlay. This window is crucial for controlling the game but can be minimized.
   • Ensure your hand is visible in the webcam window under good lighting conditions.

3. Game Controls:

   • Menus: Use your mouse to click on buttons like "Start," "Score," "Exit," or "Resume."
   • Gameplay:
     • Hold one hand up in front of the webcam.
     • Move your hand horizontally (left and right) to control the bird's position.
     • Objective: Collect the apples to score points and dodge the orange blocks. Colliding with a block will end the game.
     • Pausing: Press the ESC key or click the pause button in the top-right corner to pause the game.

Project Structure

The repository is organized as follows:

Whirleybird/
│
├── assets/
│   ├── backgrounds/    # Game backgrounds (welcome, game over, etc.)
│   ├── buttons/        # UI buttons (start, exit, etc.)
│   └── objects/        # Game sprites (bird, apple)
│
├── database/
│   └── gameScores.db   # SQLite database file for storing the high score
│
├── fonts/
│   └── BebasNeue-Regular.otf # Custom font for on-screen text
│
├── sounds/
│   └── ...             # All sound effects and music files
│
├── handTrackingModule.py   # A reusable module for MediaPipe hand detection
├── main.py                 # The main entry point and game logic script
└── README.md               # You are here!

Contributing

Contributions are welcome! If you have ideas for new features, bug fixes, or improvements, please feel free to:

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

License

This project is licensed under the MIT License. Feel free to use, modify, and distribute the code as you see fit.

Acknowledgements

• The Pygame community for creating a fantastic framework for game development in Python.
• The teams behind OpenCV and Google MediaPipe for their incredible computer vision and machine learning tools that make projects like this possible.
• All the creators of the open-source assets (images, sounds, fonts) used in this project.