# yugt/membrane-ball architecture

> Architecture diagram of the GitHub repository yugt/membrane-ball, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yugt/membrane-ball
- Repository: https://github.com/yugt/membrane-ball

## Overview

Membrane Breakout 3D is a physics-based game with a browser demo and a separate Pygame prototype. In the browser workflow, the player opens the demo, moves the membrane and rotates the camera, and the game updates the ball, collisions, bricks, and visual feedback. The Python prototype implements a parallel simulation using its own physics module. Energy displays and numerical verification expose the coupled ball–membrane behavior. The excerpts show the core physics and portions of each game loop; some browser wiring and Python gameplay details are not fully sampled, so uncertain links are omitted.

Main entry points: [`game_web/game.js`](https://github.com/yugt/membrane-ball/blob/main/game_web/game.js) (Game loop), [`game_web/index.html`](https://github.com/yugt/membrane-ball/blob/main/game_web/index.html) (Demo page), [`game_python/game.py`](https://github.com/yugt/membrane-ball/blob/main/game_python/game.py) (Pygame game loop), [`game_python/physics.py`](https://github.com/yugt/membrane-ball/blob/main/game_python/physics.py) (Membrane physics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser game"]
  node_webpage["Demo page<br/>[index.html]"]
  node_webgame["Game loop<br/>[game.js]"]
  node_webphysics["Membrane solver<br/>[game.js]"]
  node_webplay["Gameplay and collisions<br/>[game.js]"]
  node_webview["3D view and HUD<br/>[game.js]"]
  node_webaudio["Bounce audio<br/>[game.js]"]
end

subgraph group_python["Python prototype"]
  node_pygame["Pygame game loop<br/>[game.py]"]
  node_pyphysics["Membrane physics<br/>[physics.py]"]
  node_pyenergy["Energy display<br/>[game.py]"]
end

subgraph group_verification["Physics verification"]
  node_energycheck["Energy verifier<br/>[verify_energy.py]"]
  node_stagecheck["Stage verifier"]
  node_pycheck["Prototype verifier<br/>[verify_physics.py]"]
end

node_player(("Player"))
node_browser["Web browser"]
node_three["Three.js CDN"]
node_pythonplayer(("Python player"))

node_player -->|"opens demo"| node_browser
node_browser -->|"loads"| node_webpage
node_webpage -->|"loads game"| node_webgame
node_player -->|"controls paddle"| node_webgame
node_webgame -->|"updates physics"| node_webphysics
node_webgame -->|"updates gameplay"| node_webplay
node_webgame -->|"updates display"| node_webview
node_webgame -->|"plays bounces"| node_webaudio
node_webpage -.->|"loads dependency"| node_three
node_pythonplayer -->|"plays prototype"| node_pygame
node_pygame -->|"uses physics"| node_pyphysics
node_pygame -->|"updates display"| node_pyenergy
node_energycheck --> node_stagecheck
node_pycheck -->|"uses physics"| node_pyphysics

click node_webpage "https://github.com/yugt/membrane-ball/blob/main/game_web/index.html"
click node_webgame "https://github.com/yugt/membrane-ball/blob/main/game_web/game.js"
click node_webphysics "https://github.com/yugt/membrane-ball/blob/main/game_web/game.js"
click node_webplay "https://github.com/yugt/membrane-ball/blob/main/game_web/game.js"
click node_webview "https://github.com/yugt/membrane-ball/blob/main/game_web/game.js"
click node_webaudio "https://github.com/yugt/membrane-ball/blob/main/game_web/game.js"
click node_pygame "https://github.com/yugt/membrane-ball/blob/main/game_python/game.py"
click node_pyphysics "https://github.com/yugt/membrane-ball/blob/main/game_python/physics.py"
click node_pyenergy "https://github.com/yugt/membrane-ball/blob/main/game_python/game.py"
click node_energycheck "https://github.com/yugt/membrane-ball/blob/main/verify_energy.py"
click node_stagecheck "https://github.com/yugt/membrane-ball/blob/main/verify_physics_stage5.py"
click node_pycheck "https://github.com/yugt/membrane-ball/blob/main/game_python/verify_physics.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webpage,node_webgame,node_webphysics,node_webplay,node_webview,node_webaudio,node_browser toneBlue
class node_pygame,node_pyphysics,node_pyenergy toneAmber
class node_energycheck,node_stagecheck,node_pycheck toneMint
class node_player,node_three,node_pythonplayer toneIndigo
```

## Components

### Browser game

- [Demo page](https://github.com/yugt/membrane-ball/blob/main/game_web/index.html): `game_web/index.html`
- [Game loop](https://github.com/yugt/membrane-ball/blob/main/game_web/game.js): `game_web/game.js`
- [Membrane solver](https://github.com/yugt/membrane-ball/blob/main/game_web/game.js): `game_web/game.js`
- [Gameplay and collisions](https://github.com/yugt/membrane-ball/blob/main/game_web/game.js): `game_web/game.js`
- [3D view and HUD](https://github.com/yugt/membrane-ball/blob/main/game_web/game.js): `game_web/game.js`
- [Bounce audio](https://github.com/yugt/membrane-ball/blob/main/game_web/game.js): `game_web/game.js`

### Python prototype

- [Pygame game loop](https://github.com/yugt/membrane-ball/blob/main/game_python/game.py): `game_python/game.py`
- [Membrane physics](https://github.com/yugt/membrane-ball/blob/main/game_python/physics.py): `game_python/physics.py`
- [Energy display](https://github.com/yugt/membrane-ball/blob/main/game_python/game.py): `game_python/game.py`

### Physics verification

- [Energy verifier](https://github.com/yugt/membrane-ball/blob/main/verify_energy.py): `verify_energy.py`
- [Stage verifier](https://github.com/yugt/membrane-ball/blob/main/verify_physics_stage5.py): `verify_physics_stage5.py`
- [Prototype verifier](https://github.com/yugt/membrane-ball/blob/main/game_python/verify_physics.py): `game_python/verify_physics.py`

### Other components

- **Player**
- **Web browser**
- **Three.js CDN**
- **Python player**

## Connections

- Player → Web browser: opens demo
- Web browser → Demo page: loads
- Demo page → Game loop: loads game
- Player → Game loop: controls paddle
- Game loop → Membrane solver: updates physics
- Game loop → Gameplay and collisions: updates gameplay
- Game loop → 3D view and HUD: updates display
- Game loop → Bounce audio: plays bounces
- Demo page → Three.js CDN: loads dependency
- Python player → Pygame game loop: plays prototype
- Pygame game loop → Membrane physics: uses physics
- Pygame game loop → Energy display: updates display
- Energy verifier → Stage verifier
- Prototype verifier → Membrane physics: uses physics