How techwithtim/neat-flappy-bird works
Project Type and Purpose
• This is a Python-based demonstration tool that uses the NEAT (NeuroEvolution of Augmenting Topologies) algorithm to train an AI to play Flappy Bird.
• The core deliverables are:
• flappy_bird.py – orchestrates the game loop, neural network evaluation, and evolution cycle
• config-feedforward.txt – NEAT configuration file
• best.pickle – the serialized “champion” genome after training
• imgs/ – game asset directory (bird, pipe, background images)
File Structure Analysis
• Top-level scripts:
• flappy_bird.py (main orchestrator)
• Configuration: config-feedforward.txt (NEAT-Python parameters)
• Data artifacts: best.pickle (pickled best genome)
• Assets: imgs/ (PNG images for Pygame)
• Environment descriptors: requirements.txt, .replit, .gitpod.yml
• README.md explains usage: “run flappy_bird.py” and mentions NEAT Python module
Key Components & Responsibilities
A. Game Environment (Pygame)
• Loads images from imgs/
• Presents pipes, bird sprite, handles physics & collision
• Provides state vector (e.g., bird y-position, distance to next pipe)
B. NEAT Engine (neat-python library)
• Reads config-feedforward.txt
• Maintains a population of Genomes (neural nets)
• Evaluates each genome by playing the game environment
• Assigns fitness based on survival/time/score
• Applies selection, crossover, mutation to evolve new generation
C. Orchestrator Script (flappy_bird.py)
• Initializes NEAT config and population
• Loops through generations, feeding environment state → neural net → action
• Updates environment with neural net outputs (flap or do nothing)
• Tracks fitness, checkpoints population, saves best genome to best.pickle
• Loads best.pickle and/or NEAT log/statistics files
• Renders fitness-over-time graphs, species diversity charts
• Draws the neural network topology of the best genome
E. Configuration Store & Artifacts
• config-feedforward.txt (text file)
• best.pickle (serialized model)
• requirements.txt (dependency list)
Relationships & Data Flows
• flappy_bird.py → reads → config-feedforward.txt
• flappy_bird.py → imports → neat, pygame, pickle
• flappy_bird.py → loads → imgs/ assets
• flappy_bird.py → creates → NEAT Population
• NEAT Population ↔ Game Environment (state in, action out)
• NEAT Engine → evolves → Genomes → best.pickle
Architectural Patterns & Principles
• Separation of Concerns:
• Game rendering/physics (Pygame)
• AI evolution logic (neat-python)
• Result visualization
• Modular Configuration: config file separated from code
• Data Persistence: pickled genome, logging for reproducibility
• Single-Process, Event-Loop Driven (no microservices)