5e627aa50c
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
OcheCompanion
An Android darts companion app for scoring X01 games (301, 501) with automatic Double Out enforcement, bust detection, and intelligent checkout suggestions. Features player squad management with career statistics, match history tracking, and quick-start practice mode.
Features
Game Scoring
- X01 Game Support - Play standard darts games (301, 501, etc.)
- Double Out Enforcement - Automatically enforces finishing with doubles
- Bust Detection - Prevents invalid scores and reverts turns
- Checkout Suggestions - Intelligent route recommendations for finishing combinations
- Custom Keyboard - Intuitive numeric input with multiplier selection (Single, Double, Triple)
Player Management
- Squad Roster - Maintain your team with profile pictures
- Career Statistics - Track average scores and matches played per player
- Custom Profiles - Add players with personalized avatars
Match History
- Match Tracking - Complete history of all played games
- Detailed Recaps - View winners, scores, and participant information
- Persistent Storage - All data saved locally using Room database
Quick Features
- Quick Start Mode - Launch practice games instantly without database persistence
- Material Design UI - Modern, intuitive interface with custom views
Tech Stack
- Language: Java
- Architecture: MVVM pattern
- Database: Room Persistence Library
- UI Components: Material Design, Custom Views
- Image Loading: Glide
- Min SDK: 24 (Android 7.0)
Project Structure
app/src/main/java/com/aldo/apps/ochecompanion/
├── MainMenuActivity.java # Main entry point
├── GameActivity.java # Live game scoring
├── AddPlayerActivity.java # Player creation
├── database/
│ ├── AppDatabase.java # Room database singleton
│ ├── dao/
│ │ ├── PlayerDao.java # Player CRUD operations
│ │ └── MatchDao.java # Match CRUD operations
│ └── objects/
│ ├── Player.java # Player entity
│ └── Match.java # Match entity
├── models/
│ └── Match.java # Match model
└── ui/
├── MatchRecapView.java # Custom match recap view
├── PlayerItemView.java # Custom player card view
├── QuickStartButton.java # Quick start button
├── CropOverlayView.java # Image cropping overlay
└── adapter/
├── MainMenuPlayerAdapter.java
└── MainMenuGroupMatchAdapter.java
Getting Started
Prerequisites
- Android Studio Arctic Fox or later
- JDK 11 or later
- Android SDK with API Level 24+
Installation
- Clone the repository:
git clone https://github.com/yourusername/OcheCompanion.git
-
Open the project in Android Studio
-
Sync Gradle files
-
Run the app on an emulator or physical device
Building
./gradlew assembleDebug
Running Tests
./gradlew test
Usage
- Add Players - Tap the add button to create player profiles
- Start a Game - Select players and choose game type (301, 501, etc.)
- Score Throws - Use the custom keyboard to input dart scores
- Finish Games - Follow checkout suggestions to finish with doubles
- View History - Review past matches and statistics
Game Rules
- Games use standard X01 format (301, 501, etc.)
- Players must finish by hitting a double (Double Out)
- Busting (going below zero or landing on 1) reverts the turn
- Checkout suggestions appear when score is 170 or below
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
- Darts rules and checkout combinations from standard competitive play
- Material Design guidelines from Google
- Android Architecture Components
Built with ❤️ for dart players