An Android app for tracking games of Kelly Pool — a billiards elimination variant where players are secretly assigned numbered balls (1–15) and are knocked out when their balls are potted. The last player standing wins.
- Flexible setup — supports 2 to 9 players with a configurable number of balls per player
- Randomised ball assignment — balls are shuffled and distributed fairly; remaining balls become "Free Balls" that eliminate no one
- Private reveal — ball assignments are shown one player at a time so others can't peek
- Live game tracking — interactive ball grid lets you tap a ball to record it being potted, with confirmation dialogs to prevent mistakes
- Automatic elimination — players are removed from the game as their balls are potted; the winner is announced when only one player remains
- Rotation-safe — all game state is saved and restored across device rotations and process death
| Screen | Purpose |
|---|---|
| Home | Launch screen |
| Setup | Choose number of players and balls per player |
| Player Entry | Enter player names (auto-filled as "Player N" if left blank) |
| Ball Assignment | Reveals each player's assigned balls privately, one player at a time |
| Game | Live ball grid with player scores and elimination tracking |
- Language: Java 8
- Platform: Android (minSdk 24 / Android 7.0, targetSdk 34 / Android 14)
- UI: AndroidX AppCompat, Material Design 3, ConstraintLayout
- Build: Android Gradle Plugin 8.6, Gradle Version Catalog
app/src/main/java/com/example/kellypool/
├── MainActivity.java # Launch screen
├── SetUpGameActivity.java # Game configuration
├── PlayerEntryActivity.java # Player name input
├── ShowAssignedBallsActivity.java # Ball assignment reveal
├── GameActivity.java # Live game play
└── GameLogic.java # Pure Java game logic (no Android dependencies)
GameLogic.java is intentionally decoupled from Android so it can be tested on the JVM without an emulator.
- Open the project in Android Studio
- Sync Gradle dependencies
- Run on a device or emulator with Android 7.0+
# Unit tests (JVM, no emulator required)
./gradlew test
# Instrumented tests (requires connected device or emulator)
./gradlew connectedAndroidTestThe unit test suite (GameLogicTest.java) covers ball shuffling, assignment distribution, player ball counts, and winner detection.
- Each player is secretly assigned one or more numbered balls from the set (1–15)
- Players take turns shooting as in regular pool
- When a ball is potted, the player assigned to that ball loses it
- A player is eliminated when all their balls have been potted
- The last surviving player wins
Any unassigned balls are "Free Balls" — potting them has no effect on any player.