Classic Snake Gameplay: Navigate the snake, eat food, and avoid collisions
Configurable Difficulty: Adjust snake speed (1-10) and starting length (1+)
Sound Effects & Music: Optional background music and sound effects for game events
High Score Tracking: Persistent high scores stored in your home directory
Game Statistics: Track total games played, average score, and best score
Pause Menu: Press ESC to pause with game timer and quick menu access
Responsive Controls: Arrow keys for direction, quick restart capability
Terminal-Friendly: Works in any terminal with proper escape sequence support

Installation

Requirements

Python 3.12+
Pygame (for sound/music)

Setup

Clone the repository:

git clone <repo-url>
cd snake

Install dependencies using Poetry:

poetry install

Or with pip:

pip install pygame>=2.6.1

Usage

Basic Game

python snake.py

Command Line Options

python snake.py [OPTIONS]

Options:

--music - Enable background music by default
--no-effects - Disable sound effects
--no-music - Disable music toggle in the main menu

Examples:

# Play with music enabled by default
python snake.py --music

# Play without any sound
python snake.py --no-effects --no-music

# Disable music but keep sound effects
python snake.py --no-music

Controls

Key	Action
Arrow Keys	Move snake (↑↓←→)
ESC	Pause/Resume game
R	Restart game (during play or at game over)
M	Return to main menu
Q	Quit game

During Pause

ESC - Resume game
R - Restart current game
M - Return to main menu
Q - Quit the game

Configuration

Game Settings

The game saves your preferences in ~/.snake_config.json:

Snake length
Snake speed
Sound effect preference
Music preference
Character customization

High Scores

High scores and game statistics are stored in ~/.snake_scores.json:

Current high score
Game history with timestamps
Total games played
Average score

Customizing Characters

Edit ~/.snake_config.json to customize the game characters:

{
  "head_char": "█",      // Snake head character
  "body_char": "▓",      // Snake body character
  "food_char": "█"       // Food character
}

Popular character alternatives:

Head: @, O, ◉, ●
Body: o, ░, ▒, ●
Food: *, ✦, ◆, ❤

Game Statistics

After each game, your score is automatically saved. View statistics at the main menu:

High Score: Your best score ever
Total Games: Number of games played
Game Duration: Elapsed time for current game

Sound

Sound Effects

Start - Game begins
Eat - Snake eats food
Wall - Hit wall/collision
Self - Hit own body
Over - Game ends

Background Music

The game includes optional background music that loops during gameplay. Music can be toggled from the main menu.

Project Structure

snake/
├── snake.py           # Main game engine
├── constants.py       # Game constants and configuration
├── theme.py          # Color and theme management
├── sound_manager.py  # Sound effects and music handling
├── high_score.py     # Score tracking and statistics
├── game_config.py    # User preferences persistence
├── effects/          # Sound effect files
├── music/            # Background music files
└── README.md         # This file

Architecture Improvements

This version includes several improvements over the original:

Modular Design: Separated concerns into dedicated modules
Configuration Management: Persistent user preferences
Score Tracking: High score system with statistics
Better Error Handling: Graceful fallback for missing sound files
Type Hints: Comprehensive type annotations
CLI Arguments: Command-line options for common settings
Fixed Bugs:
- Fixed infinite recursion in input validation
- Fixed file path issues (works from any directory)
- Better curses state management
- Proper process cleanup

Troubleshooting

No Sound

Check that sound files exist in the effects/ and music/ directories
Ensure pygame is properly installed: pip install pygame
Try with --no-effects flag if system has audio issues

Terminal Too Small

Ensure your terminal is at least 20 columns wide and 10 rows tall
Resize your terminal window and restart the game

Curses Errors

Ensure you're running on a Unix-like system (Linux, macOS)
For Windows, install Windows Terminal or use WSL
Try running with: TERM=xterm python snake.py

High Score Not Saving

Check that ~/.snake_config.json and ~/.snake_scores.json are writable
Ensure sufficient disk space in home directory

Performance

Smooth frame rate independent of terminal size
Minimal CPU usage with event-based sound processing
Efficient collision detection
No flickering with proper buffer management

Future Ideas

Potential enhancements for future versions:

Obstacles on map
Multiple difficulty modes (Easy/Medium/Hard/Expert)
Leaderboard system
Custom map editor
Power-ups and special items
Different game modes (Endless, Time Attack, etc.)
Color themes user selection

License

MIT License - See LICENSE file for details

Author

mReschke Productions

Changelog

v0.2.0 (Current)

Complete refactor with modular architecture
Added high score tracking and statistics
Added configuration management
Fixed input validation bug (infinite recursion)
Fixed file path issues for cross-directory execution
Added CLI argument support
Improved pause menu with elapsed time
Better error handling for missing files
Comprehensive type hints
Enhanced documentation

v0.1.0

Initial release
Basic snake gameplay
Sound effects and music
Curses-based UI