# Google Play Games Integration for ZenTap

This document outlines the Google Play Games Services integration added to the ZenTap Flutter Flame game.

## Features Implemented

### 🏆 Achievements
- **First Bubble**: Pop your first bubble
- **100 Bubbles**: Pop 100 bubbles in total
- **1000 Bubbles**: Pop 1,000 bubbles in total
- **5000 Bubbles**: Pop 5,000 bubbles in total
- **Zen Master**: Play in Zen mode for 10 minutes
- **Speed Demon**: Reach 1,000 points in under 2 minutes
- **Perfect Session**: Complete a session without missing any bubbles (minimum 50 bubbles)

### 📊 Leaderboards
- **High Score**: Highest score in regular mode
- **Zen Mode Duration**: Longest time spent in Zen mode
- **Total Bubbles Popped**: Lifetime bubble count
- **Longest Session**: Longest single game session

### 🎮 Game Integration
- Automatic tracking of bubble pops, session time, and scores
- Real-time achievement checking
- Automatic submission of scores to leaderboards
- Session statistics tracking (perfect sessions, streaks, etc.)

## Setup Required

### 1. Google Play Console Configuration

1. **Create Google Play Games Project**:
   - Go to [Google Play Console](https://play.google.com/console)
   - Create a new game or link to existing app
   - Note down the App ID

2. **Configure Achievements**:
   ```
   Achievement ID: achievement_first_bubble
   Name: First Bubble
   Description: Pop your first bubble
   Points: 5
   Type: Standard
   
   Achievement ID: achievement_100_bubbles
   Name: Bubble Rookie
   Description: Pop 100 bubbles
   Points: 10
   Type: Standard
   
   Achievement ID: achievement_1000_bubbles
   Name: Bubble Master
   Description: Pop 1,000 bubbles
   Points: 25
   Type: Standard
   
   Achievement ID: achievement_5000_bubbles
   Name: Bubble Legend
   Description: Pop 5,000 bubbles
   Points: 50
   Type: Standard
   
   Achievement ID: achievement_zen_master
   Name: Zen Master
   Description: Meditate for 10 minutes in Zen mode
   Points: 30
   Type: Standard
   
   Achievement ID: achievement_speed_demon
   Name: Speed Demon
   Description: Score 1,000 points in under 2 minutes
   Points: 25
   Type: Standard
   
   Achievement ID: achievement_perfect_session
   Name: Perfect Session
   Description: Complete a session without missing any bubbles
   Points: 20
   Type: Standard
   ```

3. **Configure Leaderboards**:
   ```
   Leaderboard ID: leaderboard_high_score
   Name: High Score
   Order: Larger is better
   Score Format: Numeric
   
   Leaderboard ID: leaderboard_zen_mode
   Name: Zen Mode Duration
   Order: Larger is better
   Score Format: Time (seconds)
   
   Leaderboard ID: leaderboard_total_bubbles
   Name: Total Bubbles Popped
   Order: Larger is better
   Score Format: Numeric
   
   Leaderboard ID: leaderboard_longest_session
   Name: Longest Session
   Order: Larger is better
   Score Format: Time (seconds)
   ```

### 2. Android App Configuration

1. **Update App ID**:
   - Replace `YOUR_GOOGLE_PLAY_GAMES_APP_ID` in `android/app/src/main/res/values/strings.xml` with your actual App ID from Google Play Console

2. **App Signing**:
   - Ensure your app is signed with the same certificate used in Google Play Console
   - Upload your SHA-1 fingerprint to Google Play Console

### 3. Testing

1. **Internal Testing**:
   - Add test accounts in Google Play Console
   - Use internal testing track to test Google Play Games integration

2. **Debug Mode**:
   - Use debug keystore for development testing
   - Add debug SHA-1 to Google Play Console for testing

## Usage

### For Players
1. **Sign In**: Go to Settings and tap "Sign In" under Google Play Games
2. **View Achievements**: Tap "Achievements" to see progress
3. **View Leaderboards**: Tap "Leaderboards" to compete with others
4. **Automatic Tracking**: All game progress is automatically tracked when signed in

### For Developers
- All Google Play Games functionality is handled automatically
- Statistics are tracked during gameplay
- Results are submitted when game sessions end
- UI provides sign-in/sign-out and access to achievements/leaderboards

## File Structure

```
lib/
├── utils/
│   └── google_play_games_manager.dart    # Main Google Play Games service
├── ui/
│   └── google_play_games_widget.dart     # UI component for settings
└── game/
    └── zentap_game.dart                  # Game integration (updated)

android/
├── app/
│   ├── build.gradle.kts                  # Added Google Play Services dependencies
│   └── src/main/
│       ├── AndroidManifest.xml          # Added Google Play Games permissions
│       └── res/values/
│           └── strings.xml               # App ID configuration
```

## Dependencies Added
- `games_services: ^4.0.0` - Flutter plugin for Google Play Games Services

## Notes
- Google Play Games Services is only available on Android
- iOS Game Center integration would require additional setup
- All achievement and leaderboard IDs must match exactly between code and Google Play Console
- Test thoroughly before production release

## Troubleshooting

### Common Issues
1. **App ID Mismatch**: Ensure the App ID in strings.xml matches Google Play Console
2. **SHA-1 Fingerprint**: Make sure the app's SHA-1 is added to Google Play Console
3. **Achievement IDs**: Verify all achievement IDs match between code and console
4. **Permissions**: Ensure INTERNET and ACCESS_NETWORK_STATE permissions are added

### Debug Tips
- Check Android logs for Google Play Games errors
- Use Google Play Console's testing tools
- Verify app is properly signed for production