# santifiorino/dino-reinforcement-learning architecture

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

- Interactive diagram: https://gitdiagram.com/santifiorino/dino-reinforcement-learning
- Repository: https://github.com/santifiorino/dino-reinforcement-learning

## Overview

##### Project Type and Purpose
- This project is a game simulation combined with an AI learning system. It uses evolutionary reinforcement learning (via a genetic algorithm) to train an AI agent to play the Dino Game.
- The implementation uses Processing as the core platform for interactive graphics and simulation, with all code written from scratch in Processing’s PDE files.

##### File Structure
- The project consists entirely of Processing PDE files along with a README file and sketch properties. The key files are:
- Brain.pde – Likely defines the neural network or decision-making logic for the AI.
- Dino.pde – Contains the logic for the main character (the Dino) controlled by the AI.
- Enemy.pde – Manages obstacles or the “Enemy” objects in the game.
- GameObject.pde – Defines general properties and behaviors common to game entities.
- Genome.pde – Implements the genetic algorithm features (mutation, crossover, etc.) for learning.
- LinearAlgebra.pde – Provides mathematical support for the AI (e.g., operations on vectors/matrices).
- Simulation.pde – Orchestrates the simulation runs, managing game pacing and generations.
- main.pde – Acts as the entry point to initialize and launch the program.
- The structure indicates a separation between game display/logic (Dino, Enemy, GameObject) and the AI learning mechanism (Brain, Genome, LinearAlgebra).

##### README for Additional Insights
- The README confirms that the project implements reinforcement learning through evolutionary algorithms to teach an AI agent how to play the Dino Game.
- It explains that the project was developed in Processing to allow a ground-up understanding of AI model mechanics.

a. Main Components:
- Processing Environment: The overall runtime (Processing IDE) in which the simulation runs.
- Game Engine / Simulation Core: Represented by Simulation.pde and main.pde.
- Game Entities: Including Dino (Dino.pde), Enemy (Enemy.pde), and the base GameObject (GameObject.pde).
- AI and Learning Subsystem: Consisting of Brain.pde, Genome.pde, and LinearAlgebra.pde, which collectively implement the reinforcement learning and genetic algorithm.

b. Relationships and Interactions:
- main.pde launches the application, initializes the simulation, and brings all components together.
- The Simulation module controls the game loop, periodically updating game entities such as the Dino and Enemy.
- LinearAlgebra utilities support computations within the AI, assisting both Brain and Genome.
- The Enemy component generates obstacles which affect the simulation, indirectly impacting the learning evolution.

c. Architectural Patterns:
- Separation of Concerns: Distinct divisions between game logic (simulation and game entity classes) and the evolutionary learning logic.
- Evolutionary Loop/Feedback Cycle: A loop where simulation results provide feedback to the AI learning module (Genome evolves the Brain based on performance in Dino).
- Object-Oriented Design: Components like Dino, Enemy, and GameObject likely follow OOP principles for code reuse and encapsulation.

d. Mention Relevant Technologies and Frameworks:
- Processing is used as the visual and interactive framework.
- The project is self-contained with custom implementations for AI (reinforcement learning + genetic algorithm) and necessary linear algebra, without relying on external ML libraries.

## Diagram (Mermaid)

```mermaid
graph TD
    A["Processing Environment (sketch.properties)"]:::environment
    E["Project Documentation (readme.md)"]:::documentation

    subgraph "Simulation Core"
        B1["main.pde"]:::simulation
        B2["Simulation.pde"]:::simulation
    end

    subgraph "Game Entities"
        C1["Dino.pde"]:::gameentity
        C2["Enemy.pde"]:::gameentity
        C3["GameObject.pde"]:::gameentity
    end

    subgraph "AI Learning Subsystem"
        D1["Brain.pde"]:::ai
        D2["Genome.pde"]:::ai
        D3["LinearAlgebra.pde"]:::ai
    end

    %% Relationships
    A -->|"launches"| B1
    A -->|"launches"| B2
    B1 -->|"updates"| C1
    B1 -->|"updates"| C2
    B1 -->|"updates"| C3
    B2 -->|"controls"_simulation| D1
    C1 -->|"performance"| D2
    D2 -->|"updateParams"| D1
    D1 -->|"controls"| C1
    B1 -->|"feedback"| D2

    %% Documentation linkage
    A -->|"documents"| E

    %% Click Events
    click A "https://github.com/santifiorino/dino-reinforcement-learning/blob/main/sketch.properties"
    click B1 "https://github.com/santifiorino/dino-reinforcement-learning/blob/main/main.pde"
    click B2 "https://github.com/santifiorino/dino-reinforcement-learning/blob/main/Simulation.pde"
    click C1 "https://github.com/santifiorino/dino-reinforcement-learning/blob/main/Dino.pde"
    click C2 "https://github.com/santifiorino/dino-reinforcement-learning/blob/main/Enemy.pde"
    click C3 "https://github.com/santifiorino/dino-reinforcement-learning/blob/main/GameObject.pde"
    click D1 "https://github.com/santifiorino/dino-reinforcement-learning/blob/main/Brain.pde"
    click D2 "https://github.com/santifiorino/dino-reinforcement-learning/blob/main/Genome.pde"
    click D3 "https://github.com/santifiorino/dino-reinforcement-learning/blob/main/LinearAlgebra.pde"
    click E "https://github.com/santifiorino/dino-reinforcement-learning/blob/main/readme.md"

    %% Styles
    classDef environment fill:#f9e79f,stroke:#7d6608,stroke-width:2px;
    classDef simulation fill:#aed6f1,stroke:#21618c,stroke-width:2px;
    classDef gameentity fill:#f5cba7,stroke:#943126,stroke-width:2px;
    classDef ai fill:#abebc6,stroke:#1e8449,stroke-width:2px;
    classDef documentation fill:#fad7a0,stroke:#d35400,stroke-width:2px;
```
