# greerviau/snakeai architecture

> Architecture diagram of the GitHub repository greerviau/snakeai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/greerviau/snakeai
- Repository: https://github.com/greerviau/snakeai

## Overview

##### Main Components
a. Game Engine & Simulation: This includes the Processing sketch (SnakeAI.pde) as the entry-point where the game loop, rendering, and overall simulation are managed.
b. Snake Entity: Represented by the Snake.pde file. Each snake has its own behavior dictated by a neural network and game rules.
c. Neural Network Module: Implemented in NeuralNet.pde and Matrix.pde, where each snake’s “brain” is computed. This module handles the input layer (24 neurons from vision in 8 directions × 3 data points), hidden layers (configurable, e.g., two layers of 16 neurons), and output layer (4 possible movement directions).
d. Evolution Engine: Comprising Population.pde and EvolutionGraph.pde, this module manages the genetic algorithm aspects such as natural selection, crossover, mutation, fitness evaluation, and subsequent generation creation.
e. UI Elements: The Button.pde file provides UI components within the Processing sketch for interactions – possibly for starting, pausing, or otherwise controlling the simulation.

##### Relationships and Interactions Between Components
- The Game Engine initiates and continuously updates the simulation, orchestrating the actions of the Snake entity and querying its neural network for movement decisions.
- Each Snake instance uses its associated Neural Network module to determine moves based on sensory inputs: vision in 8 directions (food, self, and wall proximity).
- The Population module manages a collection of Snake objects. At the end of each generation (when all snakes have perished), it computes fitness scores (integrating survival time and scores) and performs reproduction via crossover and mutation with the Neural Network data.
- The EvolutionGraph component takes fitness data from the population and produces visual graphs to track progress in score evolution between generations.
- The UI (using Button components) provides a user interface within the Processing environment to possibly trigger events like saving or loading models, or to view the current evolution state.
- Data persistence is achieved by saving neural network weights and evolution data to the “data” folder, facilitating model testing in new scenarios.

##### Architectural Patterns and Design Principles
- The project follows a simulation loop pattern common in game development, where the main loop continuously processes input, updates game state, and renders the simulation.
- The separation of concerns is evident: Game control, neural network calculation, evolutionary algorithms, UI, and data storage are split into distinct modules (each with its own .pde file).
- Use of modular design allows for interchangeability (e.g., customizing the neural network architecture or tweaking evolution parameters).

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Game Engine (SnakeAI.pde)"]:::simulation
    B["Snake Entity (Snake.pde)"]:::simulation
    subgraph "Neural Network Module"
        C1["NeuralNet.pde"]:::ai
        C2["Matrix.pde"]:::ai
    end
    subgraph "Evolution Engine"
        D1["Population.pde"]:::ai
        D2["EvolutionGraph.pde"]:::ai
    end
    E["UI Elements (Button.pde)"]:::ui
    F["Data Persistence & Visualization (data)"]:::data

    A -->|"updates"| B
    B -->|"sends_sensor_data"| C1
    C1 -->|"move_decision"| B
    B -->|"fitness_data"| D1
    D1 -->|"new_generation"| A
    D2 -->|"save_evolution_data"| F
    C1 -->|"save_NN_weights"| F
    E -->|"control_commands"| A

    click A "https://github.com/greerviau/snakeai/blob/master/SnakeAI/SnakeAI.pde"
    click B "https://github.com/greerviau/snakeai/blob/master/SnakeAI/Snake.pde"
    click C1 "https://github.com/greerviau/snakeai/blob/master/SnakeAI/NeuralNet.pde"
    click C2 "https://github.com/greerviau/snakeai/blob/master/SnakeAI/Matrix.pde"
    click D1 "https://github.com/greerviau/snakeai/blob/master/SnakeAI/Population.pde"
    click D2 "https://github.com/greerviau/snakeai/blob/master/SnakeAI/EvolutionGraph.pde"
    click E "https://github.com/greerviau/snakeai/blob/master/SnakeAI/Button.pde"
    click F "https://github.com/greerviau/snakeai/tree/master/SnakeAI/data"

    classDef simulation fill:#AEDFF7,stroke:#000,stroke-width:2px;
    classDef ai fill:#F7E7A7,stroke:#000,stroke-width:2px;
    classDef ui fill:#B2F7EF,stroke:#000,stroke-width:2px;
    classDef data fill:#F7B2A7,stroke:#000,stroke-width:2px;
```
