Made use of the DatabaseHelper in all cases now.

Fixed continue logic by moving it to onResume
2026-02-06 15:45:19 +01:00
parent e2ec4f478e
commit 796e0e4389
7 changed files with 467 additions and 209 deletions
--- a/README.md
+++ b/README.md
@@ -1,70 +1,118 @@
-# OcheCompanion
+# Oche Companion

-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.
+An Android darts companion app for scoring X01 games (301, 501, 701) with automatic Double Out enforcement, bust detection, and intelligent checkout suggestions. Features comprehensive player statistics with heatmap visualization, career tracking, match history, sound effects, and configurable settings.

 ## Features

-### Game Scoring
- **X01 Game Support** - Play standard darts games (301, 501, etc.)
+### 🎯 Game Scoring
+- **X01 Game Support** - Play standard darts games (301, 501, 701, 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
+- **Bust Detection** - Prevents invalid scores and reverts turns with visual/haptic feedback
+- **Intelligent Checkout Engine** - Real-time route recommendations for finishing combinations (≤170)
 - **Custom Keyboard** - Intuitive numeric input with multiplier selection (Single, Double, Triple)
+- **Turn Indicators** - Visual dart pills showing current turn progress (3 darts max)
+- **Sound Effects** - Audio feedback for wins, busts, and perfect 180 scores
+- **Undo Support** - Remove last dart or revert entire turn
+- **GameManager Architecture** - Clean separation of business logic from UI via singleton pattern

-### 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
+### 👥 Player Management
+- **Squad Roster** - Maintain your team with custom profile pictures
+- **Advanced Statistics** - Comprehensive career tracking including:
+  - Total matches played and win rate
+  - Average score per dart and per turn
+  - Highest checkout and best game average
+  - Segment-by-segment hit frequency (singles, doubles, triples, bull)
+  - Total darts thrown and 180s scored
+- **Heatmap Visualization** - Interactive dartboard showing hit frequency with color-coded intensity
+- **Player Stats Dashboard** - Dedicated view with scrollable statistics and performance metrics
+- **Image Cropping** - Custom crop overlay for profile picture editing with zoom controls (0.1x - 10x)

-### 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
+### 📊 Match History
+- **Match Tracking** - Complete history of all played games with timestamps
+- **Detailed Recaps** - View winners, final scores, and participant information
+- **Persistent Storage** - All data saved locally using Room database with proper relationships
+- **Match Resume** - Load and continue unfinished matches

-### Quick Features
+### ⚙️ Settings & Customization
+- **Settings Activity** - Dedicated preferences screen
+- **Day/Night Mode** - Theme selection for comfortable viewing
+- **Standard Game Mode** - Configure default starting score (301, 501, 701)
 - **Quick Start Mode** - Launch practice games instantly without database persistence
- **Material Design UI** - Modern, intuitive interface with custom views
+
+### 🎨 UI/UX
+- **Material Design 3** - Modern, polished interface with custom views
+- **Confetti Celebrations** - Visual effects for game wins
+- **Responsive Layouts** - Optimized for various screen sizes
+- **Custom Views** - Purpose-built components (HeatmapView, PlayerStatsView, MatchRecapView, etc.)
+- **Vibration Feedback** - Haptic responses for busts and key actions
+- **BaseActivity** - Centralized theme management across all activities

 ## Tech Stack

- **Language**: Java
- **Architecture**: MVVM pattern
- **Database**: Room Persistence Library
- **UI Components**: Material Design, Custom Views
+- **Language**: Java 11
+- **Architecture**: MVVM pattern with singleton GameManager
+- **Database**: Room Persistence Library with DAOs
+- **UI Components**: Material Design 3, Custom Views
 - **Image Loading**: Glide
- **Min SDK**: 24 (Android 7.0)
+- **Animations**: Konfetti (confetti effects)
+- **Audio**: SoundPool API for low-latency game sounds
+- **Data Serialization**: Gson (for complex data structures)
+- **Min SDK**: 24 (Android 7.0 Nougat)
+- **Target SDK**: 36

 ## Project Structure

 ```
 app/src/main/java/com/aldo/apps/ochecompanion/
-├── MainMenuActivity.java          # Main entry point
-├── GameActivity.java              # Live game scoring
-├── AddPlayerActivity.java         # Player creation
+├── MainMenuActivity.java              # Main entry point with player list & match history
+├── GameActivity.java                  # Live game scoring UI controller
+├── AddPlayerActivity.java             # Player creation with image cropping
+├── SettingsActivity.java              # App preferences and configuration
+├── BaseActivity.java                  # Base activity for theme management
+├── game/
+│   └── GameManager.java              # Singleton business logic manager
 ├── database/
-│   ├── AppDatabase.java          # Room database singleton
+│   ├── AppDatabase.java              # Room database singleton
+│   ├── DatabaseHelper.java           # Database operations helper
 │   ├── dao/
-│   │   ├── PlayerDao.java        # Player CRUD operations
-│   │   └── MatchDao.java         # Match CRUD operations
+│   │   ├── PlayerDao.java            # Player CRUD operations
+│   │   ├── MatchDao.java             # Match CRUD operations
+│   │   └── StatisticsDao.java        # Statistics 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
+│       ├── Player.java               # Player entity
+│       ├── Match.java                # Match entity
+│       └── Statistics.java           # Statistics entity
+├── ui/
+│   ├── HeatmapView.java              # Dartboard heatmap visualization
+│   ├── PlayerStatsView.java          # Comprehensive stats dashboard
+│   ├── MatchRecapView.java           # Custom match recap view
+│   ├── PlayerItemView.java           # Custom player card view
+│   ├── QuickStartButton.java         # Quick start button
+│   ├── CropOverlayView.java          # Image cropping overlay
+│   ├── PlayerSelectionDialogFragment.java  # Player picker dialog
+│   ├── MainMenuPreferencesFragment.java    # Settings fragment
+│   └── adapter/
+│       ├── MainMenuPlayerAdapter.java
+│       ├── MainMenuGroupMatchAdapter.java
+│       └── PlayerSelectionAdapter.java
+└── utils/
+    ├── CheckoutEngine.java           # Checkout route calculation
+    ├── CheckoutConstants.java        # Pre-calculated checkout routes (2-170)
+    ├── DartsConstants.java           # Game constants (scores, multipliers, labels)
+    ├── UIConstants.java              # UI constants (colors, animations, scales)
+    ├── SoundEngine.java              # Singleton sound effect manager
+    ├── ResourceHelper.java           # Resource utilities
+    ├── Log.java                      # Custom logging wrapper
+    ├── MatchProgress.java            # Match state serialization
+    └── converters/
+        ├── IntListConverter.java     # Room type converter for lists
+        └── MatchProgressConverter.java  # Room type converter for match state
 ```

 ## Getting Started

 ### Prerequisites
- Android Studio Arctic Fox or later
+- Android Studio Hedgehog or later
 - JDK 11 or later
 - Android SDK with API Level 24+

@@ -79,7 +127,7 @@ git clone https://github.com/yourusername/OcheCompanion.git

 3. Sync Gradle files

-4. Run the app on an emulator or physical device
+4. Run the app on an emulator or physical device (API 24+)

 ### Building

@@ -95,18 +143,43 @@ git clone https://github.com/yourusername/OcheCompanion.git

 ## Usage

-1. **Add Players** - Tap the add button to create player profiles
-2. **Start a Game** - Select players and choose game type (301, 501, etc.)
-3. **Score Throws** - Use the custom keyboard to input dart scores
-4. **Finish Games** - Follow checkout suggestions to finish with doubles
-5. **View History** - Review past matches and statistics
+### Getting Started
+1. **Add Players** - Tap the add button (+) to create player profiles with custom avatars
+2. **Configure Settings** - Access settings to choose day/night mode and default game type
+3. **Start a Match** - Select players from your roster and choose starting score (301, 501, 701)
+4. **Quick Practice** - Use Quick Start button for instant practice games without saving
+
+### During a Game
+1. **Select Multiplier** - Choose Single, Double, or Triple before each dart
+2. **Tap Numbers** - Input dart scores using the numeric keyboard (1-20 or Bull)
+3. **Follow Suggestions** - Checkout routes appear automatically when score ≤ 170
+4. **Undo Mistakes** - Use undo button to remove last dart
+5. **Submit Turn** - Advance to next player after 3 darts or when ready
+6. **View Stats** - Tap player card to see detailed statistics and heatmap
+
+### After a Game
+1. **Review Match** - View match recap with winner and final scores
+2. **Check Statistics** - Access player stats to see updated career metrics
+3. **View History** - Browse past matches in the main menu

 ## 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
+- Games use standard X01 format (301, 501, 701, etc.)
+- Players must finish by hitting a double (Double Out rule)
+- Busting (going below zero or landing on exactly 1) reverts the entire turn
+- Checkout suggestions appear when remaining score is 170 or below
+- Maximum of 3 darts per turn
+- Perfect score of 180 (Triple 20 × 3) triggers special celebration
+
+## Code Quality
+
+This project follows Android best practices:
+- ✅ **No Magic Numbers** - All constants extracted to centralized constant classes
+- ✅ **Comprehensive Documentation** - JavaDoc comments on all public methods
+- ✅ **MVVM Architecture** - Clear separation of concerns
+- ✅ **Singleton Pattern** - GameManager and SoundEngine for efficient resource management
+- ✅ **Type Safety** - Room database with compile-time verification
+- ✅ **Proper Naming** - Android conventions (m-prefix for members, s-prefix for statics)

 ## License

@@ -117,6 +190,7 @@ This project is licensed under the MIT License - see the LICENSE file for detail
 - Darts rules and checkout combinations from standard competitive play
 - Material Design guidelines from Google
 - Android Architecture Components
+- Sound effects for game events

 ---