Oche Companion

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, 701, etc.)
• Double Out Enforcement - Automatically enforces finishing with doubles
• 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 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 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

⚙️ 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

🎨 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 11
• Architecture: MVVM pattern with singleton GameManager
• Database: Room Persistence Library with DAOs
• UI Components: Material Design 3, Custom Views
• Image Loading: Glide
• 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 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
│   ├── DatabaseHelper.java           # Database operations helper
│   ├── dao/
│   │   ├── PlayerDao.java            # Player CRUD operations
│   │   ├── MatchDao.java             # Match CRUD operations
│   │   └── StatisticsDao.java        # Statistics CRUD operations
│   └── objects/
│       ├── 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 Hedgehog or later
• JDK 11 or later
• Android SDK with API Level 24+

Installation

1. Clone the repository:

git clone https://github.com/yourusername/OcheCompanion.git

2. Open the project in Android Studio

3. Sync Gradle files

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

Building

./gradlew assembleDebug

Running Tests

./gradlew test

Usage

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, 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

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
• Sound effects for game events

---

Built with ❤️ for dart players