# js1b/simple-physics-engine architecture

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

- Interactive diagram: https://gitdiagram.com/js1b/simple-physics-engine
- Repository: https://github.com/js1b/simple-physics-engine

## Overview

##### Project type and purpose
- This is a Python‑based, open‑source physics engine library with rendering (OpenGL) and input handling (Pygame).
- Its focus is on simulating rigid‑body dynamics (gravity, friction, collisions) and providing a simple API for embedding in applications or running the example scripts (e.g., Newton’s cradle).

##### File structure
- Top‑level:
- setup.py, requirements‑dev.txt – packaging, development dependencies
- examples/ – demonstration scripts
- simplephysicsengine/ – core library
- tests/ – unit tests
- In `simplephysicsengine/`:
- engine.py – main simulation loop, orchestrates subsystems
- physics.py – physics calculations (forces, integrations, collisions)
- objects/ – rigid‑body definitions (ball, string, world container)
- gl_object.py – OpenGL rendering abstraction
- key_mappings.py, config_loader.py, config/key_mappings.json – input mapping and configuration
- mixins.py – shared behavior utilities for objects

##### README for additional insights
- Confirms core capabilities: rigid‑body dynamics, gravity, friction, collisions

##### Final advice
- Be very detailed: break down the Object Model into its parts (world, ball, string) if space allows.
- Avoid over‑complicating: represent each Python module or folder as a distinct component.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Example Layer
    subgraph "Example Applications"
        EX["examples/newton_cradle.py"]:::examples
    end

    %% Core Library
    subgraph "Core Library"
        subgraph "Engine Layer"
            EN["Simulation Engine\n(engine.py)"]:::core
        end
        subgraph "Physics Module"
            PH["Physics Module\n(physics.py)"]:::core
        end
        subgraph "Object Model"
            WD["World\n(world.py)"]:::core
            BA["Ball\n(ball.py)"]:::core
            ST["String\n(string.py)"]:::core
            MX["Mixins\n(mixins.py)"]:::core
        end
    end

    %% I/O Subsystem
    subgraph "I/O Subsystem"
        IN["Input Subsystem\n(key_mappings.py)"]:::io
        RE["Rendering Subsystem\n(gl_object.py)"]:::io
    end

    %% Configuration
    subgraph "Configuration"
        CL["Config Loader\n(config_loader.py)"]:::config
        KM["Key Mappings JSON\n(key_mappings.json)"]:::config
    end

    %% External Libraries
    subgraph "External Libraries"
        PG["Pygame"]:::external
        GL["PyOpenGL"]:::external
    end

    %% Packaging & Development
    subgraph "Packaging & Dev"
        STP["setup.py"]:::meta
        REQ["requirements-dev.txt"]:::meta
    end

    %% Tests
    subgraph "Tests"
        TE["tests/test_engine.py"]:::tests
        TC["tests/test_config_loader.py"]:::tests
        PI["tests/pytest.ini"]:::tests
    end

    %% Connections
    EX -->|initialize| EN
    EN -->|poll events| IN
    IN -->|map keys| EN
    EN -->|"invoke physics"| PH
    PH -->|update world| WD
    PH -->|update ball| BA
    PH -->|update string| ST
    EN -->|apply mixins| MX
    EN -->|draw frame| RE
    RE -->|render calls| GL
    IN -->|event loop| PG
    CL -->|read config| KM
    CL -->|provide mappings| IN

    %% Click Events
    click EN "https://github.com/js1b/simple-physics-engine/blob/main/simplephysicsengine/engine.py"
    click PH "https://github.com/js1b/simple-physics-engine/blob/main/simplephysicsengine/physics.py"
    click WD "https://github.com/js1b/simple-physics-engine/blob/main/simplephysicsengine/objects/world.py"
    click BA "https://github.com/js1b/simple-physics-engine/blob/main/simplephysicsengine/objects/ball.py"
    click ST "https://github.com/js1b/simple-physics-engine/blob/main/simplephysicsengine/objects/string.py"
    click RE "https://github.com/js1b/simple-physics-engine/blob/main/simplephysicsengine/gl_object.py"
    click IN "https://github.com/js1b/simple-physics-engine/blob/main/simplephysicsengine/key_mappings.py"
    click CL "https://github.com/js1b/simple-physics-engine/blob/main/simplephysicsengine/config_loader.py"
    click KM "https://github.com/js1b/simple-physics-engine/blob/main/simplephysicsengine/config/key_mappings.json"
    click MX "https://github.com/js1b/simple-physics-engine/blob/main/simplephysicsengine/mixins.py"
    click EX "https://github.com/js1b/simple-physics-engine/blob/main/examples/newton_cradle.py"
    click STP "https://github.com/js1b/simple-physics-engine/blob/main/setup.py"
    click REQ "https://github.com/js1b/simple-physics-engine/blob/main/requirements-dev.txt"
    click TE "https://github.com/js1b/simple-physics-engine/blob/main/tests/test_engine.py"
    click TC "https://github.com/js1b/simple-physics-engine/blob/main/tests/test_config_loader.py"
    click PI "https://github.com/js1b/simple-physics-engine/blob/main/tests/pytest.ini"

    %% Styles
    classDef core fill:#E3F2FD,stroke:#2196F3,color:#0D47A1
    classDef io fill:#E8F5E9,stroke:#43A047,color:#1B5E20
    classDef config fill:#FFF3E0,stroke:#FB8C00,color:#E65100
    classDef external fill:#FBE9E7,stroke:#D84315,color:#BF360C
    classDef examples fill:#F3E5F5,stroke:#8E24AA,color:#4A148C
    classDef meta fill:#ECEFF1,stroke:#607D8B,color:#263238
    classDef tests fill:#FAFAFA,stroke:#9E9E9E,color:#424242
```
