🧠 NeuroFlap

An AI-powered Flappy Bird built from scratch in Python with Pygame and a custom neural network, trained using an evolutionary algorithm.

---

🚀 Overview

NeuroFlap simulates Flappy Bird gameplay where a bird learns to navigate pipes using a simple neural network evolved over generations.

✨ Highlights:

• Pure Python — no external ML libraries.
• Neural net evolves through genetic algorithms (no gradient descent, no backprop).
• Real-time rendering with Pygame.
• Includes manual play mode (you can play too!).

---

🎮 Features

✅ Flappy Bird game (Pygame engine)
✅ Custom neural network (fully connected layers + softmax)
✅ Genetic algorithm: selection + mutation
✅ Save/load best performing model
✅ User mode to play yourself
✅ Classic style score display (number sprites)
✅ Game over + restart functionality

---

📝 How it works

• main.py → Lets you play Flappy Bird manually (spacebar to flap).
• evolve.py → Runs the evolutionary training to evolve the AI.
• best_model.py → Loads and runs the best saved AI agent automatically.

---

📂 Project structure

NeuroFlap/
├── Saved/
│   └── best_flappy_weights.npz   # Saved AI model weights
├── best_model.py                 # Run the best trained agent
├── custom_nn.py                  # Neural network building blocks
├── evolve.py                     # Evolutionary training loop
├── flappy.py                     # Flappy Bird game environment
├── main.py                       # User play mode (manual play)
├── neural_net.py                  # Neural network wrapper for Flappy
├── requirements.txt               # Python dependencies
├── .gitignore
└── README.md                      # Project documentation

---

⚡ Getting started

Requirements

• Python 3.7+
• Pygame
• NumPy

Install dependencies

pip install -r requirements.txt

---

🕹️ Running

Play manually

python main.py

Train AI using genetic algorithm

python evolve.py

Watch trained AI play

python best_model.py

---

📌 License

Licensed under the GNU General Public License v3.0.
See LICENSE.

---

<<<<<<< HEAD

🤝 Contributions

PRs and suggestions welcome — feel free to fork and improve NeuroFlap!

bd0f5bc (Added assets and a Player mode)