This commit introduces a complete statistics tracking and visualization system for the Oche Companion darts app, addressing multiple race condition issues and enhancing user experience with audio/vibration feedback controls.
MAJOR FEATURES:
Statistics & Database (Breaking Changes)
- Upgraded Room database from v10 to v12 with destructive migration
- Added hit distribution map (Map<String, Integer>) to Statistics entity
- Implemented HitDistributionConverter with Gson for Map<->JSON persistence
- Registered TypeConverter at database level for automatic conversion
- Expanded Statistics entity to track:
* Scoring milestones (60+, 100+, 140+, 180)
* First 9 darts average (starting consistency metric)
* Checkout statistics (successful finishes, highest checkout)
* Double-out attempt tracking (success/miss rates)
* Hit distribution for heat map visualization
* Matches played counter
GameActivity Enhancements
- Added DartHit inner class to track baseValue and multiplier per dart
- Implemented parallel tracking with mCurrentTurnDartHits list
- Created recordTurnHitsToStatistics() for hit distribution updates
- Added trackDoubleAttempt() for double-out success/failure recording
- Added incrementMatchesPlayed() called on match completion
- Fixed checkout value calculation (final dart, not full turn score)
- Fixed bust tracking (addMissedDarts instead of saveDartsThrown)
- Renamed Statistics getters/setters for consistency:
* dartsThrown -> totalDartsThrown
* overallPointsMade -> totalPoints
* doubleOutsTargeted -> totalDartsAtDouble
CRITICAL BUG FIXES:
Race Condition Resolution
- Fixed list clearing race: Pass copies (new ArrayList<>) to background threads
- Fixed database race: Added per-player synchronization locks (mPlayerStatsLocks HashMap)
- Implemented double synchronized block pattern:
1. synchronized(mPlayerStatsLocks) to get/create player lock
2. synchronized(lock) to protect entire READ-MODIFY-WRITE operation
- Allows concurrent updates for different players while preventing data corruption
User Feedback System
- Added audio/vibration feedback toggle preferences
- Implemented SharedPreferences reading in onResume()
- Added conditional checks (mIsAudioEnabled, mIsVibrationEnabled) throughout
- Created preference UI with toggle buttons and dynamic icons
- Added Day/Night auto mode with mutual exclusion logic
Visualization Components
- Created HeatmapView custom view extending View
- Implements dartboard rendering with Canvas path calculations
- Color interpolation from cold (faded) to hot (volt green)
- Splits board into concentric rings: doubles, outer singles, triples, inner singles
- Added TestActivity for heatmap development/debugging
- Added navigation from MainMenuActivity title click to TestActivity
UI/UX Improvements
- Added vector drawables for audio/vibration states (on/off)
- Enhanced preferences screen with categorized sections
- Improved settings fragment with preference interaction logic
- Added Gson dependency (v2.13.2) for JSON serialization
Code Quality
- Added comprehensive JavaDoc to all new Statistics methods
- Made all method parameters final for immutability
- Added detailed logging for statistics operations
- Improved error handling with try-catch blocks in background threads
TECHNICAL NOTES:
- Database migration is DESTRUCTIVE (all data lost on schema change)
- Per-player locks enable parallel statistics updates across players
- Hit distribution keys use format: "t20", "d16", "s5", "sb", "db"
- Heatmap normalizes weights against max hits for consistent coloring
- Statistics now tracks 15+ distinct performance metrics
TESTING RECOMMENDATIONS:
- Verify hit distribution persists correctly across matches
- Test concurrent multi-player statistics updates
- Confirm checkout values reflect final dart, not turn total
- Validate milestone counters increment accurately
- Test heatmap visualization with varied hit patterns
BREAKING CHANGE: Database schema updated from v3 to v9 (destructive migration)
Major Features:
- Statistics system: Track player performance (darts, points, matches, double-outs)
- Match state management: ONGOING/COMPLETED/CANCELED with state-based queries
- Settings activity: Day/night mode and standard game mode preferences
- CheckoutEngine refactored to standalone utility class with 1/2/3-dart methods
CheckoutConstants Overhaul:
- Generate all possible double-out combinations (~37,200 routes)
- Intelligent route selection (fewer darts > T20/T19 > higher doubles)
- Store both optimal routes and complete alternatives
GameActivity Enhancements:
- Automatic statistics tracking on turn submission and win
- Career average calculation and database updates
- Fixed race condition with dart value capture
Database Changes:
- Added Statistics entity and StatisticsDao
- Player ID migration: int → long for consistency
- Match entity: added MatchState enum and helper methods
- MatchDao: new state-based query methods
Developer Experience:
- Comprehensive JavaDoc across all new/modified classes
- Test harness for checkout generation validation
- Improved code organization with utils package separation
