Flappy Bird

A modern, visually stunning implementation of the classic Flappy Bird game in Python with zero external assets. Built with pure Pygame rendering and particle effects.

Gameplay

• Classic Flappy Bird mechanics with smooth physics simulation
• Responsive controls - Multiple input methods (Keyboard & Mouse)
• High score tracking - Persistent best score display
• Progressive difficulty - Consistent pipe spawning with random gaps
• Screen shake effects - Visual feedback on collisions

Code Architecture

• Object-oriented design - Clean separation of concerns (Bird, Pipe, Game classes)
• Delta-time based physics - Frame-rate independent movement
• State machine - Menu, Playing, Game Over, and Paused states
• Particle physics - Realistic acceleration and lifetime management
• Collision detection - Precise rectangular collision with pipes and boundaries

Controls

Control	Action
SPACE / UP / W	Make bird flap
CLICK	Start game or flap during play
ESC	Pause/Resume game
SPACE (Game Over)	Restart game

Installation

Requirements

• Python 3.7+
• Pygame 2.0+

Setup

Clone or Download

git clone https://github.com/infinitecoder1729/Flappy-Bird
cd Flappy-bird

Create Virtual Environment (Recommended)

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

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

Install Dependencies

pip install pygame

Run the Game

python flappy-bird.py

How to Play

1. Start the game by pressing SPACE or clicking the window
2. Avoid the pipes by making your bird flap to navigate through gaps
3. Earn points - Gain 1 point for each pipe successfully passed
4. Minimize time in air - Don't let your bird hit the ground or ceiling
5. Beat your high score - Your best score is displayed at the menu
6. Pause anytime - Press ESC to pause/resume the game

Tips for High Scores

• Time your flaps - Small, controlled flaps work better than mashing the button
• Aim for center - Try to pass through the middle of each pipe gap
• Watch the rotation - Bird angle indicates velocity; negative angle = ascending
• Anticipate pipes - Prepare your flap just before entering a pipe gap

Game Mechanics

Physics System

Gravity:        0.4 px/frame²
Flap Power:    -9 px/frame
Max Velocity:  ~15 px/frame (downward)
Pipe Speed:    -4 px/frame (leftward)
Pipe Gap:      120 px

Difficulty

• Pipe Spawn Rate: Every 2.0 seconds
• Random Gaps: Generated between 50-430 px from top
• No difficulty scaling - Consistent challenge throughout

Collision Detection

• Bird vs Pipes: Bounding box collision with top and bottom pipes
• Bird vs Boundaries: Y-position bounds checking (0 to SCREEN_HEIGHT)
• Pipe Passing: Score awarded when bird's X crosses pipe's right edge

Visual Components

Bird Design

• Body: Animated circle with color-coded state
• Eye: Direction indicator with pupil highlight
• Wing: Dynamic polygon that reflects movement
• Particles: Colorful dots emitted on flap

Pipe Design

• Dual-pipe system: Top and bottom obstacles with consistent gap
• 3D effect: Shadow borders and highlight stripes
• Color-coded: Distinct green coloring for clarity
• Smooth rendering: Anti-aliased edges

Background

• Gradient sky: Blue gradient from light to darker tone
• Decorative ground: Textured grass pattern at bottom
• Dynamic shaking: Screen distortion on collision

Code Architecture

Game
├── Bird (Entity)
│   ├── Position (x, y)
│   ├── Velocity
│   ├── Particles[]
│   └── Methods: flap(), update(), draw()
│
├── Pipe (Entity)
│   ├── Position (x)
│   ├── Gap Position (gap_y)
│   └── Methods: update(), draw(), collides_with()
│
├── Particle (Entity)
│   ├── Physics (velocity, acceleration)
│   ├── Lifetime
│   └── Methods: update(), draw()
│
└── Game Loop
    ├── Input Handling
    ├── State Management
    ├── Physics Update
    ├── Collision Detection
    └── Rendering

Customization

Modify Game Constants

Edit the constants at the top of flappy-bird.py:

# Screen dimensions
SCREEN_WIDTH = 400
SCREEN_HEIGHT = 600

# Physics
GRAVITY = 0.4
FLAP_POWER = -9

# Pipes
PIPE_VELOCITY = -4
PIPE_GAP = 120

Change Colors

All colors are defined as RGB tuples:

COLOR_BIRD = (255, 200, 87)  # Bird color
COLOR_PIPE = (60, 200, 80)   # Pipe color
COLOR_BG_LIGHT = (135, 206, 250)  # Sky color

Adjust Difficulty

Modify spawn intervals and pipe gap variations:

self.pipe_spawn_interval = 1.8  # Spawn faster (was 2.0)
MIN_PIPE_HEIGHT = 40  # Tighter gaps (was 50)

Testing

Unit Testing Template

import unittest
from flappy_bird import Bird, Pipe, Game

class TestBird(unittest.TestCase):
    def setUp(self):
        self.bird = Bird(100, 100)
    
    def test_flap(self):
        initial_velocity = self.bird.velocity
        self.bird.flap()
        self.assertEqual(self.bird.velocity, FLAP_POWER)
    
    def test_gravity(self):
        self.bird.update(1.0)
        self.assertGreater(self.bird.velocity, 0)

class TestCollision(unittest.TestCase):
    def test_pipe_collision(self):
        bird = Bird(50, 100)
        pipe = Pipe(100, 80)
        self.assertTrue(pipe.collides_with(bird))

if __name__ == '__main__':
    unittest.main()

Performance

Optimization Features

• Delta-time based updates - Consistent behavior at any frame rate
• Lazy particle removal - Particles cleaned up after lifetime expires
• Efficient collision detection - Minimal rect calculations
• Off-screen pipe cleanup - No memory leaks from hidden pipes

Typical Performance

• FPS: 60 FPS (locked by FPS constant)
• CPU Usage: <5% on modern systems
• Memory: ~30 MB (including Python runtime)
• Latency: <16ms per frame

Gameplay Statistics

Scoring

• Points awarded: 1 per successfully passed pipe
• Score display: Top-center of screen in gold
• High score: Shown in menu and game-over screen
• Accuracy: Pixel-perfect scoring on pipe passing

Death Conditions

1. Ceiling collision - Bird Y < 0
2. Ground collision - Bird Y + size >= SCREEN_HEIGHT
3. Top pipe collision - Bird rect intersects top pipe
4. Bottom pipe collision - Bird rect intersects bottom pipe

Troubleshooting

Game won't start

Error: pygame module not found
Solution: pip install pygame --upgrade

Game runs slowly

Error: Low FPS
Solution: 
- Close background applications
- Reduce particle spawn rate
- Lower screen resolution (edit SCREEN_WIDTH/HEIGHT)

Bird moves erratically

Error: Inconsistent physics
Solution:
- Verify FPS is set to 60
- Check delta-time calculation
- Ensure no frame skipping

Contributing

How to Contribute

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

Ideas for Contribution

• Add sound effects
• Implement difficulty levels
• Create mobile version
• Add achievements system
• Implement online leaderboard
• Create custom themes

Support

• Issues: Report bugs on GitHub Issues
• Discussions: Join GitHub Discussions for ideas
• Feedback: Share your high scores and gameplay tips!

Hall of Fame

Share your high scores! Comment on the repository with your best score.

🥇 Champion: [Your Score] - [Your Name]
🥈 Runner-up: [Score] - [Name]
🥉 Third Place: [Score] - [Name]

---

Happy flapping! ✨

Made with ❤️ using Python and Pygame

Last Updated: December 2025
Version: 1.0 (First Edition)
Python: 3.7+
Pygame: 2.0+