DEVELOPMENT.md

Advanced Snake Game - Developer Documentation

Project Overview

This is an advanced implementation of the classic Snake game using Python and Pygame. The project demonstrates modern game development practices including state management, object-oriented programming, and persistent data storage.

Development Guidelines

Code Style

• Follow PEP 8 conventions
• Use descriptive variable names
• Add docstrings to all functions and classes
• Keep functions focused and single-purpose

Architecture

Enums

• GameState: Defines game states for proper state management
• Difficulty: Defines difficulty levels with associated settings

Classes

• HighScoreManager: Handles persistent score storage

Main Functions

• gameloop(): Main game loop with state management
• draw_menu(): Renders main menu
• draw_difficulty_menu(): Renders difficulty selection
• draw_paused_screen(): Renders pause screen
• draw_game_over_screen(): Renders game over screen
• text_screen(): Renders text on screen
• plot_snake(): Renders snake segments

Game Flow

START
  ↓
MENU
  ├─ S → DIFFICULTY
  └─ Q → QUIT
  ↓
DIFFICULTY
  ├─ 1-4 → PLAYING
  └─ Q → MENU
  ↓
PLAYING
  ├─ P → PAUSED
  ├─ Q → QUIT (with high score save)
  └─ Collision → GAME_OVER
  ↓
PAUSED
  └─ P → PLAYING
  ↓
GAME_OVER
  ├─ ENTER → DIFFICULTY
  ├─ M → MENU
  └─ Q → QUIT

Configuration

Window Settings

• Width: 800px
• Height: 600px
• Title: "🐍 Advanced Snake Game"

Snake Settings

• Size: 20px per segment
• Growth: 1 segment per food item

Difficulty Settings

EASY: speed=4, color=green
MEDIUM: speed=8, color=yellow
HARD: speed=12, color=red
EXTREME: speed=16, color=magenta

Testing

Manual Testing Checklist

Menu Navigation:

• Start button works
• Quit button works
• High score displays correctly

Difficulty Selection:

• All 4 difficulties are selectable
• Back button returns to menu
• Selected difficulty affects snake color

Gameplay:

• Snake moves correctly with arrow keys
• Food spawns at random locations
• Collision detection works
• Score increases correctly
• Pause/Resume works
• Speed increases every 5 points

High Scores:

• High scores persist between sessions
• New high score is detected
• High score file is created automatically

Edge Cases:

• Game handles window close gracefully
• No infinite recursion on replay
• High score updates correctly

Performance Considerations

• Game loop runs at 60 FPS base, variable during gameplay
• Collision detection uses simple distance calculation (O(n) for self-collision)
• JSON file I/O only happens on score/quit events
• Memory usage is minimal due to simple data structures

Future Improvements

High Priority

• Add sound effects
• Implement power-ups
• Add obstacles

Medium Priority

• Leaderboard system
• Statistics tracking
• Custom themes

Low Priority

• Networking/multiplayer
• Advanced AI
• Network leaderboards

Debugging Tips

1. FPS Issues: Check system resources and adjust base FPS if needed
2. Collision Problems: Review collision detection logic in gameloop()
3. High Score Not Saving: Verify highscore.json file permissions
4. Screen Issues: Check pygame display settings

Resources

• Pygame Documentation: https://www.pygame.org/docs/
• Python PEP 8: https://www.python.org/dev/peps/pep-0008/
• Game Development Best Practices: https://gamedevelopment.tutsplus.com/

Contact & Support

For issues or questions, please open an issue on GitHub.