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