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:

git clone <repo-url>
cd snake

2. 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:

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