# shuhuagao/gpflappybird architecture

> Architecture diagram of the GitHub repository shuhuagao/gpflappybird, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shuhuagao/gpflappybird
- Repository: https://github.com/shuhuagao/gpflappybird

## Overview

This is a Pygame Flappy Bird game that evolves a Cartesian Genetic Programming (CGP) policy to control AI birds. The main workflow initializes a population, runs game generations, scores birds by survival, and evolves the population; a bird’s policy evaluates the front pipe’s vertical offset, horizontal distance, and gap to decide whether to flap. A human can join and control a bird during play. After evolution, the entry point can extract, simplify, and optionally visualize evolved formulas. The game/evolution loop is supported by sampled source; some update and evolution details are only partially excerpted.

Main entry points: [`game.py`](https://github.com/shuhuagao/gpflappybird/blob/master/game.py) (Game controller), [`main_entry.py`](https://github.com/shuhuagao/gpflappybird/blob/master/main_entry.py) (Program entry), [`sprites.py`](https://github.com/shuhuagao/gpflappybird/blob/master/sprites.py) (Bird and sprites), [`postprocessing.py`](https://github.com/shuhuagao/gpflappybird/blob/master/postprocessing.py) (Formula simplification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_play["Game play"]
  node_entry["Program entry<br/>[main_entry.py]"]
  node_game["Game controller<br/>[game.py]"]
  node_world["Pipes and gaps<br/>[game.py]"]
  node_sprites["Bird and sprites<br/>[sprites.py]"]
  node_input["Game controls<br/>[game.py]"]
  node_render["Game display<br/>[game.py]"]
  node_audio["Sound effects<br/>[sprites.py]"]
end

subgraph group_evolution["CGP evolution"]
  node_population["Population setup<br/>[cgp.py]"]
  node_policy["CGP policy<br/>[cgp.py]"]
  node_fitness["Survival scoring<br/>[sprites.py]"]
  node_selection["Mutation and selection<br/>[cgp.py]"]
end

subgraph group_analysis["Solution analysis"]
  node_extract["Active graph extraction<br/>[postprocessing.py]"]
  node_formula["Formula simplification<br/>[postprocessing.py]"]
  node_visualize["Graph visualization<br/>[postprocessing.py]"]
  node_formula_file["Formula output<br/>[main_entry.py]"]
  node_graph_files["Graph output<br/>[main_entry.py]"]
end

node_player(("Human player"))

node_player -->|"presses controls"| node_input
node_entry -->|"creates and runs"| node_game
node_entry -->|"initializes population"| node_population
node_game -->|"spawns pipes"| node_world
node_game -->|"creates birds"| node_sprites
node_input -->|"controls play"| node_game
node_game -->|"draws frame"| node_render
node_sprites -->|"plays effects"| node_audio
node_game -->|"requests flap decision"| node_policy
node_policy -->|"returns flap score"| node_sprites
node_sprites -->|"sets fitness on death"| node_fitness
node_game -->|"evolves generation"| node_selection
node_selection -->|"returns next generation"| node_population
node_entry -->|"extracts evolved graphs"| node_extract
node_extract -->|"provides active graph"| node_formula
node_entry -->|"simplifies formula"| node_formula
node_formula -->|"writes formula"| node_formula_file
node_entry -.->|"requests visualization"| node_visualize
node_visualize -.->|"writes graph files"| node_graph_files

click node_entry "https://github.com/shuhuagao/gpflappybird/blob/master/main_entry.py"
click node_game "https://github.com/shuhuagao/gpflappybird/blob/master/game.py"
click node_world "https://github.com/shuhuagao/gpflappybird/blob/master/game.py"
click node_sprites "https://github.com/shuhuagao/gpflappybird/blob/master/sprites.py"
click node_input "https://github.com/shuhuagao/gpflappybird/blob/master/game.py"
click node_render "https://github.com/shuhuagao/gpflappybird/blob/master/game.py"
click node_audio "https://github.com/shuhuagao/gpflappybird/blob/master/sprites.py"
click node_population "https://github.com/shuhuagao/gpflappybird/blob/master/cgp.py"
click node_policy "https://github.com/shuhuagao/gpflappybird/blob/master/cgp.py"
click node_fitness "https://github.com/shuhuagao/gpflappybird/blob/master/sprites.py"
click node_selection "https://github.com/shuhuagao/gpflappybird/blob/master/cgp.py"
click node_extract "https://github.com/shuhuagao/gpflappybird/blob/master/postprocessing.py"
click node_formula "https://github.com/shuhuagao/gpflappybird/blob/master/postprocessing.py"
click node_visualize "https://github.com/shuhuagao/gpflappybird/blob/master/postprocessing.py"
click node_formula_file "https://github.com/shuhuagao/gpflappybird/blob/master/main_entry.py"
click node_graph_files "https://github.com/shuhuagao/gpflappybird/blob/master/main_entry.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_game,node_world,node_sprites,node_input,node_render,node_audio toneBlue
class node_population,node_policy,node_fitness,node_selection toneAmber
class node_extract,node_formula,node_visualize,node_formula_file,node_graph_files toneMint
class node_player toneIndigo
```

## Components

### Game play

- [Program entry](https://github.com/shuhuagao/gpflappybird/blob/master/main_entry.py): `main_entry.py`
- [Game controller](https://github.com/shuhuagao/gpflappybird/blob/master/game.py): `game.py`
- [Pipes and gaps](https://github.com/shuhuagao/gpflappybird/blob/master/game.py): `game.py`
- [Bird and sprites](https://github.com/shuhuagao/gpflappybird/blob/master/sprites.py): `sprites.py`
- [Game controls](https://github.com/shuhuagao/gpflappybird/blob/master/game.py): `game.py`
- [Game display](https://github.com/shuhuagao/gpflappybird/blob/master/game.py): `game.py`
- [Sound effects](https://github.com/shuhuagao/gpflappybird/blob/master/sprites.py): `sprites.py`

### CGP evolution

- [Population setup](https://github.com/shuhuagao/gpflappybird/blob/master/cgp.py): `cgp.py`
- [CGP policy](https://github.com/shuhuagao/gpflappybird/blob/master/cgp.py): `cgp.py`
- [Survival scoring](https://github.com/shuhuagao/gpflappybird/blob/master/sprites.py): `sprites.py`
- [Mutation and selection](https://github.com/shuhuagao/gpflappybird/blob/master/cgp.py): `cgp.py`

### Solution analysis

- [Active graph extraction](https://github.com/shuhuagao/gpflappybird/blob/master/postprocessing.py): `postprocessing.py`
- [Formula simplification](https://github.com/shuhuagao/gpflappybird/blob/master/postprocessing.py): `postprocessing.py`
- [Graph visualization](https://github.com/shuhuagao/gpflappybird/blob/master/postprocessing.py): `postprocessing.py`
- [Formula output](https://github.com/shuhuagao/gpflappybird/blob/master/main_entry.py): `main_entry.py`
- [Graph output](https://github.com/shuhuagao/gpflappybird/blob/master/main_entry.py): `main_entry.py`

### Other components

- **Human player**

## Connections

- Human player → Game controls: presses controls
- Program entry → Game controller: creates and runs
- Program entry → Population setup: initializes population
- Game controller → Pipes and gaps: spawns pipes
- Game controller → Bird and sprites: creates birds
- Game controls → Game controller: controls play
- Game controller → Game display: draws frame
- Bird and sprites → Sound effects: plays effects
- Game controller → CGP policy: requests flap decision
- CGP policy → Bird and sprites: returns flap score
- Bird and sprites → Survival scoring: sets fitness on death
- Game controller → Mutation and selection: evolves generation
- Mutation and selection → Population setup: returns next generation
- Program entry → Active graph extraction: extracts evolved graphs
- Active graph extraction → Formula simplification: provides active graph
- Program entry → Formula simplification: simplifies formula
- Formula simplification → Formula output: writes formula
- Program entry → Graph visualization: requests visualization
- Graph visualization → Graph output: writes graph files