# Hunt Feature Documentation

## Overview
The Hunt feature is a gamified treasure hunt system that challenges users to find specific locations in their city using mystery clues. It combines augmented reality hints, location-based gaming, and social leaderboards.

## Features

### 1. Card Selection System
- **Point-based Cards**: Each card has different point values (sorted by highest points first)
- **Category System**: Cards are categorized (Coffee Shop, Restaurant, Fashion Store, etc.)
- **Animated Cards**: Smooth flip animations when selected
- **Mystery Questions**: Each card contains a riddle about a specific location

### 2. Hunt Mechanics
- **12-Hour Time Limit**: Players have 12 hours to complete their hunt
- **Real-time Timer**: Countdown timer with visual indicators
- **Location Monitoring**: Automatic detection when player reaches target location
- **Success Celebration**: Sound effects and animations upon completion

### 3. AR Hint System
- **Camera Integration**: Uses device camera for AR experience
- **Location-based Hints**: AR markers appear at specific coordinates
- **Visual Feedback**: Scanning animations and hint discovery notifications
- **Permission Handling**: Proper camera and location permission requests

### 4. Leaderboard System
- **Real-time Rankings**: Shows player position based on total points
- **User Highlighting**: Current user is highlighted in the leaderboard
- **Point Tracking**: Displays individual and total points earned
- **Animated Updates**: Smooth animations when rank changes

## Technical Implementation

### State Management
- Uses Provider pattern for state management
- `HuntState` class manages all game state
- Real-time updates for location monitoring
- Proper cleanup of resources

### Location Services
- Geolocator integration for precise location tracking
- Permission handling for location access
- Distance calculation between current and target locations
- Background location monitoring during active hunts

### Sound & Haptics
- Card flip sound effects
- Success celebration sounds
- Hint discovery feedback
- Vibration patterns for different actions

### Camera Integration
- Mobile Scanner for camera access
- AR overlay rendering
- Real-time location-based hint detection
- Custom AR UI elements

## File Structure

```
lib/screens/mains/hunt/
├── hunt.dart                    # Main hunt screen
├── models/
│   └── hunt_card.dart          # Data models
├── providers/
│   └── hunt_provider.dart      # State management
├── services/
│   ├── location_service.dart   # Location handling
│   └── game_sound_service.dart # Audio feedback
└── widgets/
    ├── hunt_card_widget.dart   # Card UI component
    ├── leaderboard_widget.dart # Leaderboard UI
    ├── hint_camera_widget.dart # AR camera interface
    └── hunt_timer_widget.dart  # Timer components
```

## Game Flow

1. **Card Selection**
   - Player sees sorted cards by points
   - Selects a card to reveal the mystery
   - Card flips with animation to show the riddle

2. **Hunt Activation**
   - 12-hour timer starts
   - Location monitoring begins
   - Player can use hints if needed

3. **Hint System**
   - Opens AR camera view
   - Shows scanning interface
   - Detects when player is near hint location
   - Provides additional clues

4. **Hunt Completion**
   - Automatic detection when player reaches target
   - Success animation and sound effects
   - Points added to player's total
   - Leaderboard position updated

## Mock Data

The feature includes comprehensive mock data:
- 5 different hunt cards with varying difficulties
- Fake leaderboard with 6 players
- Location coordinates set to: `32.62501010252744, 51.72622026956878`
- Point values ranging from 100-200 points

## UI/UX Features

### Animations
- Card flip animations (800ms duration)
- Scale animations on card selection
- Slide transitions between game states
- Pulse animations for active elements
- Confetti effect on completion

### Dark/Light Mode Support
- Dynamic color switching based on theme
- Proper contrast ratios for both modes
- Theme-aware icons and illustrations

### Professional Design
- Modern card-based interface
- Gradient backgrounds and shadows
- Proper spacing and typography
- Consistent iconography
- Responsive layout

## Permissions Required

- **Location Permission**: For hunt location tracking
- **Camera Permission**: For AR hint feature
- **Vibration**: For haptic feedback (optional)

## Future Enhancements

1. **API Integration**: Replace mock data with real backend
2. **Multiple Hunt Modes**: Daily challenges, team hunts, etc.
3. **Photo Verification**: Require photos at hunt locations
4. **Social Features**: Share achievements, invite friends
5. **Reward System**: Unlock special cards or prizes
6. **Map Integration**: Show hunt locations on map view

## Testing Notes

- Location is currently set to a fixed coordinate for testing
- All hunt cards use the same target location
- Success detection has a 50-meter radius
- Hint detection has a 100-meter radius
- Permissions are properly handled with user-friendly dialogs

## Performance Considerations

- Efficient location monitoring (5-second intervals)
- Proper animation disposal to prevent memory leaks
- Optimized AR camera rendering
- Background task cleanup on screen disposal
- Resource-conscious timer implementations