160 lines
5.3 KiB
Markdown
160 lines
5.3 KiB
Markdown
# 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
|