# 📘 **Arduino Jump Dash — Full Project README**

## 🎮 Overview

This project connects a **browser-based Geometry Dash–style game** with an **Arduino board**.
The player controls the jumping character using:

* A **physical button** connected to the Arduino
* Or the **space bar** on the keyboard
* (Optional) Touch input on mobile

The Arduino communicates with a **Node.js backend**, which relays player actions to the **browser game** using WebSockets. The game sends back **score** and **death statistics**, which the backend forwards to the Arduino. The Arduino displays these values on a **7-segment display**.

The whole system is fully bidirectional:

```
Arduino (Button) → Node Backend → Game Browser (Jump Input)
Game Browser (Score/Deaths) → Node Backend → Arduino (Seven Segment Display)
```

---

# 🧱 **Project Architecture**

```
┌──────────────────────┐     WebSocket       ┌────────────────────────┐
│  Browser Game (JS)   │  <-------------->   │ Node.js Backend        │
│ - Canvas runner      │                     │ - Express static server│
│ - Jump logic         │                     │ - WebSocket server     │
│ - Obstacle system    │                     │ - SerialPort interface │
└──────────────────────┘                     └───────────┬────────────┘
                                                         │ Serial USB
                                                         ▼
                                        ┌────────────────────────────────┐
                                        │ Arduino                        │
                                        │ - Button input                 │
                                        │ - Seven segment display output │
                                        └────────────────────────────────┘
```

---

# 🛠️ **Technologies Used**

### **Frontend**

* HTML5 Canvas
* CSS responsive layout (mobile-friendly)
* Vanilla JavaScript game engine
* WebSocket client
* Keyboard & touch controls

### **Backend**

* Node.js + Express
* WebSocket (ws)
* SerialPort (for Arduino communication)

### **Hardware**

* Arduino
* Push button (for jump input)
* Seven-segment display (via SevSeg library)

---

# 🔌 **Setup Instructions**

## 1️⃣ Install Dependencies

### **Node backend**

```bash
npm install express ws serialport
```

### **Arduino**

Install the **SevSeg** library:

**Arduino IDE → Sketch → Include Library → Manage Libraries → Search “SevSeg”**

---

# 📁 **Project Structure**

```
/project
│
├── public/
│   ├── index.html
│   ├── style.css
│   └── game.js
│
├── server.js        # Node.js backend
├── arduino.js (optional - for simulation)
└── README.md
```

---

# 🖥️ **Frontend Game Features**

* Geometry Dash–style gameplay
* Ground + obstacles moving right→left
* Player jumps with:
  * Arduino button (via WebSocket)
  * Spacebar on keyboard
  * Touch on mobile
* Scoring system:
  * +1 for every obstacle cleared
* Death detection and game over UI
* Restart button
* Fully responsive + centered canvas

---

# 🌐 **WebSocket Protocol**

### **Browser → Backend (Game Events)**

#### Score update:

```json
{
  "type": "score",
  "score": 12
}
```

#### Death event:

```json
{
  "type": "death",
  "deaths": 3
}
```

### **Backend → Browser (Jump Input)**

Sent when Arduino button is pressed:

```json
{
  "action": "jump"
}
```

---

# 🔁 **Backend Responsibilities**

* Serve the frontend game files
* Maintain WebSocket connections
* Receive serial events from Arduino (`"JUMP"`)
* Forward `"jump"` action to browser clients
* Receive score/death stats from browser
* Format and send them to Arduino via serial:

  * `S<number>` for score
  * `D<number>` for deaths

Example:

```
S15\n   → show score 15 on seven segment
D3\n    → show deaths 3 on seven segment
```

---

# 🔧 **Arduino Responsibilities**

* Detect button press → send `"JUMP\n"` via Serial
* Receive messages from backend:

  * `S##` → update score display
  * `D##` → update death count
* Use SevSeg to draw numbers on seven-segment display

Pseudo-protocol:

```
PC to Arduino:
  S42 → set score to 42  
  D7  → set death count to 7  

Arduino to PC:
  JUMP → player pressed the button
```

---

# 🧪 **Testing Without Arduino (Virtual Serial Ports)**

You can create paired virtual serial ports (e.g., using `socat` on Linux/macOS or com0com on Windows).

Then run the simulator:

```bash
node arduino.js
```

Press Enter to simulate a button press → game character jumps.

---

# 📱 **Responsive UI Features**

* Canvas centered via flexbox
* Scales with `aspect-ratio`
* Score & Game Over UI positioned relative to game container
* Mobile-friendly touch support