snake/README.md

# Snake CLI Game

A modern, feature-rich Snake game for the terminal using Python's curses library.

## Features

- **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

1. Clone the repository:
```bash
git clone <repo-url>
cd snake
```

2. Install dependencies using Poetry:
```bash
poetry install
```

Or with pip:
```bash
pip install pygame>=2.6.1
```

## Usage

### Basic Game
```bash
python snake.py
```

### Command Line Options

```bash
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:**
```bash
# 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:

```json
{
  "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:

1. **Modular Design**: Separated concerns into dedicated modules
2. **Configuration Management**: Persistent user preferences
3. **Score Tracking**: High score system with statistics
4. **Better Error Handling**: Graceful fallback for missing sound files
5. **Type Hints**: Comprehensive type annotations
6. **CLI Arguments**: Command-line options for common settings
7. **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