Eye Evolution

A neuroevolution simulation where predators and prey co-evolve neural-network-driven eyes and brains through genetic algorithms, powered by TinyML.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. How It Works
5. Roadmap
6. Contributing
7. License
8. Contact
9. Acknowledgments

About The Project

Eye Evolution is a real-time simulation that demonstrates the co-evolution of predator and prey organisms. Each organism is controlled by a neural network (powered by TinyML) whose weights and eye configurations evolve over generations via a genetic algorithm with roulette wheel selection and single-point crossover.

Key features:

• Neural-network-driven behavior -- each organism's brain is an ML::Model from TinyML that maps eye inputs to movement outputs
• Evolving eye positions -- eye placement around the body is encoded in the genome alongside network weights
• Raycasting vision -- organisms cast rays to detect predators, prey, and food in their environment
• Food foraging -- prey must balance escaping predators with collecting food to maximize fitness
• Cross-platform -- builds on macOS, Linux, and Windows via CMake with automatic dependency fetching

(back to top)

Built With

• 
• 
• 
• 

(back to top)

Getting Started

Prerequisites

• A C++17-compatible compiler (GCC 7+, Clang 5+, MSVC 2017+)
• CMake 3.16 or newer
• Git

On macOS:

brew install cmake

On Ubuntu/Debian:

sudo apt install cmake build-essential libgl-dev libx11-dev libxrandr-dev libfreetype-dev libudev-dev

On Windows, install Visual Studio with the C++ workload, or use MSYS2.

Installation

1. Clone the repo

   git clone https://github.com/godofecht/Eye-Evolution.git
   cd Eye-Evolution

2. Configure and build (CMake automatically fetches SFML and TinyML)

   cmake -B build -DCMAKE_BUILD_TYPE=Release
   cmake --build build --target EyeEvolution -j$(nproc)

3. Run

   ./build/bin/EyeEvolution

Tip: If you have tinyML cloned as a sibling directory (../tinyml-repo/), CMake will use it directly instead of fetching from GitHub.

(back to top)

Usage

Launch the simulation and watch the organisms evolve in real time. Green circles are prey, red circles are predators, and yellow diamonds are food. White rays show vision; red rays indicate a detected object.

The iteration counter (top-left) shows the current generation. Each generation runs for a fixed duration, after which the genetic algorithm selects the fittest organisms to breed the next generation.

(back to top)

How It Works

┌─────────────┐     ┌──────────────┐     ┌───────────────┐
│  Eye Inputs  │────>│  ML::Model   │────>│  Movement Vec  │
│  (raycasts)  │     │  (TinyML NN) │     │  (fwd + rot)   │
└─────────────┘     └──────────────┘     └───────────────┘
        ^                                        │
        │           ┌──────────────┐              │
        └───────────│  Environment │<─────────────┘
                    │  (SFML loop) │
                    └──────┬───────┘
                           │  end of generation
                           v
                    ┌──────────────┐
                    │   Genetic    │
                    │  Algorithm   │
                    │  (crossover) │
                    └──────────────┘

1. Perception -- Each organism casts rays from its evolved eye positions and detects nearby entities
2. Decision -- Ray hit/miss values are fed into a TinyML neural network which outputs movement commands
3. Action -- The organism moves forward and rotates based on network outputs
4. Selection -- After a fixed time, organisms are ranked by fitness and selected via roulette wheel
5. Reproduction -- Selected parents undergo single-point crossover on both weights and eye positions
6. Repeat -- New weights are injected into the population and the next generation begins

(back to top)

Roadmap

• Cross-platform CMake build system
• TinyML integration for neural networks
• Configurable simulation parameters via config file or CLI flags
• Data logging and fitness plots across generations
• Save/load evolved populations to disk
• Multiple environment topologies (walls, obstacles)

See the open issues for a full list of proposed features and known issues.

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Top contributors:

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Abhishek Shivakumar - abhishek.shivakumar@gmail.com

Project Link: https://github.com/godofecht/Eye-Evolution

(back to top)

Acknowledgments

• TinyML -- Lightweight C++ machine learning library
• SFML -- Simple and Fast Multimedia Library
• Best-README-Template

(back to top)