# Number Guessing Game

A feature-rich Python number guessing game with difficulty levels, scoring system, achievements, and colorful terminal output.

## Features

- **Multiple Difficulty Levels**: Easy, Medium, Hard, and Expert with score multipliers
- **Points-Based Scoring**: Earn points based on efficiency, difficulty, and streaks
- **Speed Bonus System**: Quick guesses (under 5 seconds) earn up to 25% bonus points
- **Win Streak System**: Build consecutive wins for bonus points (up to 50% bonus)
- **Score Breakdown**: See detailed point calculation after each win
- **Achievement System**: Unlock 8 achievements for various accomplishments
- **High Score Tracking**: Persistent leaderboard with points ranking
- **Game History**: Track your recent games within the session
- **Optimal Guess Display**: Shows binary search optimal guess count for reference
- **Colorful Terminal UI**: ANSI color-coded output for better UX
- **Hint System**: Temperature-based hints to help players
- **Input Validation**: Out-of-range guesses are rejected without using an attempt
- **Player Statistics**: Track games, wins, win rate, points, and streaks

## How to Play

```bash
# Run the game
python game.py
```

## Scoring System

Points are calculated based on:
- **Efficiency**: Fewer attempts = more points
- **Difficulty Multiplier**: Easy (1x), Medium (1.5x), Hard (2x), Expert (3x)
- **Streak Bonus**: +10% per consecutive win (caps at 50%)
- **Perfect Guess**: 2x multiplier for guessing on first try
- **Speed Bonus**: Up to 25% bonus for quick guesses (under 5 seconds average)

After each win, you'll see a detailed score breakdown showing exactly how your points were calculated.

Minimum score for any win: 100 points

## Achievements

| Achievement | Description | Emoji |
|------------|-------------|-------|
| First Victory | Win your first game | :medal: |
| Hot Streak | Win 3 games in a row | :fire: |
| Unstoppable | Win 5 games in a row | :zap: |
| Mind Reader | Guess correctly on first try | :dart: |
| Expert Player | Win on Expert difficulty | :crown: |
| High Scorer | Score over 2000 points in one game | :gem: |
| Veteran | Play 10 games | :military_medal: |
| Efficient | Win within optimal guesses | :brain: |

## Difficulty Levels

| Level  | Range    | Attempts | Hints              | Score Multiplier |
|--------|----------|----------|--------------------|------------------|
| Easy   | 1-50     | 15       | Every 2 guesses    | 1.0x             |
| Medium | 1-100    | 10       | Every 3 guesses    | 1.5x             |
| Hard   | 1-150    | 7        | Every 4 guesses    | 2.0x             |
| Expert | 1-200    | 5        | No hints           | 3.0x             |

## Menu Options

1. **Play Game** - Start a new round
2. **View Leaderboard** - See top 10 scores by points
3. **Change Difficulty** - Switch difficulty level
4. **View My Stats** - See your session statistics and achievements
5. **View Game History** - See your last 10 games
6. **View Achievements** - See all achievements and unlock status
7. **Quit** - Exit the game with final stats

## Files

- `game.py` - Main game code
- `test_game.py` - Unit tests (32 tests)
- `high_scores.json` - Persistent high score data (auto-created)
- `README.md` - This file

## Requirements

- Python 3.6+
- No external dependencies (uses only standard library)

## Running Tests

```bash
# Run all tests
python -m pytest test_game.py -v
```

## Game Mechanics

- Guess a random number within the range
- Get feedback: "Too high" or "Too low"
- Temperature hints tell you how close you are
- Win by guessing correctly before running out of attempts
- Higher points = better leaderboard position
- Build streaks for bonus points
- Unlock achievements for special accomplishments
