proxybuy-flutter/HUNT_FEATURE_README.md

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