README.md

Markdown · 157 lines

# Snake Game on LED Matrix (Gyro Controlled)

## Overview

This project implements a classic **Snake Game** on an 8×8 LED matrix, controlled using a **QMI8658 IMU (gyro/accelerometer)**. The snake moves based on tilt direction, grows when eating food, and resets upon collision.

---

## Features

* Gyroscope-based directional control
* Dynamic snake growth
* Random food spawning (avoids snake body)
* Temporary collision dodge mechanism
* Adjustable movement speed
* Visual game-over feedback on LED matrix

---

## Hardware Requirements

* 8×8 RGB LED Matrix
* QMI8658 IMU sensor
* Compatible microcontroller (ESP32 / Arduino-based board)

---

## Dependencies

* `WS_QMI8658.h` → IMU handling
* `WS_Matrix.h` → LED matrix control

---

## Game Logic

### Snake Movement

* The snake moves at fixed time intervals (`moveDelay`)
* Direction is controlled via tilt:

  * Tilt right → move right
  * Tilt left → move left
  * Tilt up → move up
  * Tilt down → move down
* Reverse movement is prevented

---

### Food System

* Food appears randomly on the grid
* Food cannot spawn on the snake
* After eating:

  * Snake length increases
  * Food disappears temporarily
  * Respawns after a random number of moves (2–7)

---

### Collision Handling

* Collisions checked for:

  * Wall boundaries (8×8 grid)
  * Snake biting itself
* A **dodge delay** prevents immediate game over after reset

---

### Game Over Behavior

* Entire matrix lights up briefly
* Snake resets to random position
* New food is spawned
* Game restarts automatically

---

## Key Variables

| Variable               | Description                             |
| ---------------------- | --------------------------------------- |
| `snakeX[]`, `snakeY[]` | Snake body coordinates                  |
| `snakeLength`          | Current snake length                    |
| `direction`            | Movement direction (1–4)                |
| `foodX`, `foodY`       | Food position                           |
| `moveDelay`            | Speed of snake movement                 |
| `dodgeDelay`           | Grace period before collision detection |
| `foodActive`           | Whether food is visible                 |
| `moveCounter`          | Tracks moves for food respawn           |

---

## Core Functions

### `controlDirection()`

Reads IMU data and updates movement direction.

### `moveSnake()`

Moves snake body and handles collision detection.

### `spawnFood()`

Generates valid food position avoiding snake overlap.

### `updateMatrix()`

Refreshes LED matrix with snake and food.

### `gameOver()`

Handles reset logic and visual feedback.

---

## Customization

### Adjust Speed

```cpp
unsigned long moveDelay = 500;
```

### Adjust Sensitivity

```cpp
float threshold = 0.1;
```

### Change Grid Size

Currently fixed at 8×8. Requires modifying:

* Boundary checks
* Matrix buffer handling

---

## Notes

* Maximum snake length is capped at 64 (full grid).
* Food spawn attempts are limited to prevent infinite loops.
* Uses simple integer grid logic for performance efficiency.

---

## Possible Improvements

* Score tracking
* Difficulty scaling (speed increase over time)
* Wrap-around mode (no wall collision)
* Sound feedback (buzzer)
* Persistent high score