124 lines
3.9 KiB
Markdown
124 lines
3.9 KiB
Markdown
# 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
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
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
|
|
|
|
### Building
|
|
|
|
```bash
|
|
./gradlew assembleDebug
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
./gradlew test
|
|
```
|
|
|
|
## 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
|
|
|
|
## 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**
|