# maxrobinsonthegreat/lifeengine architecture

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

- Interactive diagram: https://gitdiagram.com/maxrobinsonthegreat/lifeengine
- Repository: https://github.com/maxrobinsonthegreat/lifeengine

## Overview

##### Project type and purpose
- This is a client-side web application (a single-page simulation) called “The Life Engine.”
- Its purpose is to simulate biological evolution on a 2D grid (cellular automaton) in the browser.

##### File structure
- Top-level:
- package.json, webpack.config.js → build & bundling
- src/ → application source code (Controllers, Engine, Environments, Grid, Organism, Rendering, Stats, Utils)
- dist/ → compiled output (index.html, CSS, JS bundle, static JSON assets under dist/assets)
- Key directories & patterns:
- src/Controllers: UI controllers (Canvas, Load, Editor, ControlPanel, EnvironmentController, ControlModes)
- src/Engine.js: central simulation loop & tick orchestration
- src/Environments: environment abstractions (grid, organism editor, world environment)
- src/Grid & src/Organism: domain model for cells, organisms, anatomy, brain, perception
- src/Rendering: drawing logic (Renderer, ColorScheme)
- src/Stats: statistical tracking & charting components
- src/Utils: helper libraries (Perlin noise, serialization)

##### README for additional insights
- The simulation evolves organisms via reproduction, mutation, movement, perception, and selection.
- Assets (worlds, organisms, mods) are loaded as JSON from dist/assets.
- The UI exposes controls to start/stop, toggle modes, edit organisms and environments.
- Stats panel visualizes population, mutations, species over time.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        CC["CanvasController"]:::ui
        CP["ControlPanel"]:::ui
        LC["LoadController"]:::ui
        EC["EditorController"]:::ui
        EnvC["EnvironmentController"]:::ui
        CM["ControlModes"]:::ui
    end

    %% Simulation Engine
    subgraph "Simulation Engine"
        Engine["Engine"]:::engine
    end

    %% Domain Model
    subgraph "Domain Model"
        GM["GridMap"]:::model
        NB["Neighbors"]:::model
        HP["Hyperparameters"]:::model
        Org["Organism"]:::model
        Dir["Directions"]:::model
        Anat["Anatomy"]:::model
        ROG["RandomOrganismGenerator"]:::model
        subgraph "Cell Hierarchy"
            GC["GridCell"]:::model
            CS["CellStates"]:::model
            subgraph "BodyCells"
                Armor["ArmorCell"]:::model
                Body["BodyCell"]:::model
                BCF["BodyCellFactory"]:::model
                Eye["EyeCell"]:::model
                Killer["KillerCell"]:::model
                Mouth["MouthCell"]:::model
                Mover["MoverCell"]:::model
                Producer["ProducerCell"]:::model
            end
        end
        subgraph "Perception & Brain"
            Brain["Brain"]:::model
            Obs["Observation"]:::model
        end
    end

    %% Rendering Layer
    subgraph "Rendering Layer"
        Renderer["Renderer"]:::render
        CScheme["ColorScheme"]:::render
    end

    %% Statistics Module
    subgraph "Statistics Module"
        SP["StatsPanel"]:::stats
        CCtrl["ChartController"]:::stats
        Cells["CellsChart"]:::stats
        Mut["MutationChart"]:::stats
        Pop["PopulationChart"]:::stats
        SpecC["SpeciesChart"]:::stats
        FR["FossilRecord"]:::stats
        Species["Species"]:::stats
    end

    %% Environments & Editors
    subgraph "Environments & Editors"
        EnvA["Environment"]:::env
        WorldEnv["WorldEnvironment"]:::env
        OrgEdit["OrganismEditor"]:::env
    end

    %% Data Layer & Utilities
    subgraph "Data Layer & Utils"
        SH["SerializeHelper"]:::data
        Perlin["Perlin"]:::data
        WC["WorldConfig"]:::data
    end

    %% Build & Deployment
    subgraph "Build & Deployment"
        Entry["src/index.js"]:::build
        Webpack["webpack.config.js"]:::build
        PKG["package.json"]:::build
        Dist["dist/"]:::build
    end

    %% Connections
    CC -->|commands| Engine
    CP -->|commands| Engine
    LC -->|commands| Engine
    EC -->|commands| Engine
    EnvC -->|commands| Engine
    CM -->|commands| Engine

    Engine -->|updates state| GM
    Engine -->|updates state| Org
    Engine -->|emits tick| Renderer
    Engine -->|emits tick| SP

    Renderer -->|draws to UI| CC
    SP -->|updates UI| CP

    LC -->|loads assets| SH
    SH -->|instantiates| GM & Org & EnvA & WorldEnv

    Entry -->|bundled by| Webpack
    Webpack -->|outputs| Dist

    Dist -->|serves| CC
    Dist -->|serves| Renderer
    Dist -->|serves| SP

    %% Click Events
    click CC "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Controllers/CanvasController.js"
    click CP "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Controllers/ControlPanel.js"
    click LC "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Controllers/LoadController.js"
    click EC "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Controllers/EditorController.js"
    click EnvC "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Controllers/EnvironmentController.js"
    click CM "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Controllers/ControlModes.js"
    click Engine "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Engine.js"
    click GM "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Grid/GridMap.js"
    click NB "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Grid/Neighbors.js"
    click HP "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Hyperparameters.js"
    click Org "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Organism/Organism.js"
    click Dir "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Organism/Directions.js"
    click Anat "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Organism/Anatomy.js"
    click ROG "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Organism/RandomOrganismGenerator.js"
    click GC "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Organism/Cell/GridCell.js"
    click CS "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Organism/Cell/CellStates.js"
    click Armor "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Organism/Cell/BodyCells/ArmorCell.js"
    click Body "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Organism/Cell/BodyCells/BodyCell.js"
    click BCF "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Organism/Cell/BodyCells/BodyCellFactory.js"
    click Eye "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Organism/Cell/BodyCells/EyeCell.js"
    click Killer "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Organism/Cell/BodyCells/KillerCell.js"
    click Mouth "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Organism/Cell/BodyCells/MouthCell.js"
    click Mover "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Organism/Cell/BodyCells/MoverCell.js"
    click Producer "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Organism/Cell/BodyCells/ProducerCell.js"
    click Brain "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Organism/Perception/Brain.js"
    click Obs "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Organism/Perception/Observation.js"
    click Renderer "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Rendering/Renderer.js"
    click CScheme "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Rendering/ColorScheme.js"
    click SP "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Stats/StatsPanel.js"
    click CCtrl "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Stats/Charts/ChartController.js"
    click Cells "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Stats/Charts/CellsChart.js"
    click Mut "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Stats/Charts/MutationChart.js"
    click Pop "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Stats/Charts/PopulationChart.js"
    click SpecC "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Stats/Charts/SpeciesChart.js"
    click FR "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Stats/FossilRecord.js"
    click Species "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Stats/Species.js"
    click EnvA "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Environments/Environment.js"
    click WorldEnv "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Environments/WorldEnvironment.js"
    click OrgEdit "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Environments/OrganismEditor.js"
    click SH "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Utils/SerializeHelper.js"
    click Perlin "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/Utils/Perlin.js"
    click WC "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/WorldConfig.js"
    click Entry "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/src/index.js"
    click Webpack "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/webpack.config.js"
    click PKG "https://github.com/maxrobinsonthegreat/lifeengine/blob/master/package.json"

    %% Styles
    classDef ui fill:#FDEBD0,stroke:#E67E22,stroke-width:1px
    classDef engine fill:#D6EAF8,stroke:#3498DB,stroke-width:1px
    classDef model fill:#D5F5E3,stroke:#28B463,stroke-width:1px
    classDef render fill:#EBDEF0,stroke:#8E44AD,stroke-width:1px
    classDef stats fill:#F9E79F,stroke:#F1C40F,stroke-width:1px
    classDef data fill:#E5E7E9,stroke:#95A5A6,stroke-width:1px
    classDef build fill:#FCF3CF,stroke:#F39C12,stroke-width:1px
    classDef env fill:#FADBD8,stroke:#C0392B,stroke-width:1px
```
