Sudoku - A classic Android game in Java

An Android Sudoku app with a Compose-based home flow (HomeActivity + StatsActivity) that launches a Java + ViewBinding game screen (MainActivity). The game logic lives in an MVVM stack powered by SudokuViewModel, LiveData, and the SudokuBoard model, keeping the UI responsive while puzzles are generated on a background thread.

Screenshots

New Game Dialog	Game Screen

Features

• Fresh puzzles per game: Generates solvable boards with a uniqueness check before play starts.
• Difficulty selector + resume: Start a new Easy, Medium, or Hard puzzle, or resume the latest in-progress game from the Compose home screen.
• Real-time validation: Highlights wrong entries immediately; per-move scoring and an error counter keep feedback clear.
• Timer and scoring: Time-based bonus plus difficulty bonuses, with softer difficulty-scaled penalties on mistakes; score never drops below zero.
• Undo support: Revert the latest user move while keeping score in sync; the error counter remains historical across the whole game.
• Local stats: Tracks wins, best time, and best score per difficulty without introducing accounts or cloud state.
• Config-change safe: Board state, selection, timer, and counters survive rotations and process death via the ViewModel bundle.
• App-close safe: The latest in-progress game is stored locally and can be resumed after the app is fully closed.

Architecture in brief

• UI flow: HomeActivity (Compose home), optional StatsActivity (local statistics), then MainActivity (ViewBinding screen + overlayed TextViews for numbers).
• Rendering: SudokuGridView draws the grid; HighlightOverlayView draws selection/highlight layers.
• State + logic: SudokuViewModel owns UI state with LiveData, delegates rules and move history to SudokuBoard/SudokuCell.
• Background work: Puzzle generation runs on a single-thread executor; a Handler drives the in-app timer on the main thread.
• Read the full breakdown in docs/ARCHITECTURE.md.

Project structure

app/src/main/java/com/example/sudoku
├── GameStatsStore.java        # SharedPreferences-backed local wins / best time / best score tracking
├── HomeActivity.kt            # Compose launcher with resume, difficulty selection, and stats entry point
├── MainActivity.java          # ViewBinding UI, observers, dialogs, keypad, highlight overlay hookup
├── SavedGameStore.java        # SharedPreferences-backed persistence for the latest in-progress game
├── StatsActivity.kt           # Compose statistics screen with overview and per-difficulty breakdown
├── SudokuGridView.java        # Custom view that draws the 9x9 board background and grid lines
├── HighlightOverlayView.java  # Selection, row/column, and block highlighting overlay
├── SudokuBoard.java           # Core logic: puzzle generation, validation, scoring, move history
├── SudokuCell.java            # Parcelable cell model (value, fixed flag, correctness, notes)
└── viewmodel/SudokuViewModel.java  # LiveData state holder, timer, undo, and move handling

Resources live in app/src/main/res; Compose theme definitions are under app/src/main/java/com/example/sudoku/ui/theme.

Getting started

Prerequisites: Android Studio (Koala+ recommended), JDK 21, Android SDK 36; the app currently targets and requires Android 14 (minSdk 34).

1. Clone the repo: git clone https://github.com/<your-username>/Basic_Sudoku.git
2. Open the project in Android Studio and let Gradle sync.
3. Pick a device/emulator running Android 14+ and press Run, or build from the CLI with ./gradlew assembleDebug. If your shell defaults to JDK 25, switch JAVA_HOME back to JDK 21 first.

Development and testing

• Quick build: ./gradlew assembleDebug
• Release build check: ./gradlew assembleRelease
• Unit/UI tests: JVM regression tests live in app/src/test, and instrumented tests live in app/src/androidTest; run them with ./gradlew test or ./gradlew connectedAndroidTest.
• Repository quality gate: make verify runs test, assembleDebug, and lintDebug with JDK 21 wired in automatically on macOS.
• Code style: Kotlin uses the official style; Java follows standard Android conventions and lives alongside Compose code where needed.
• More tips live in docs/DEVELOPMENT.md.

Documentation

• docs/ARCHITECTURE.md: deeper dive into the UI flow, threading, scoring, and puzzle generation.
• docs/DEVELOPMENT.md: environment setup, build commands, and guidelines for extending the app.

License

This project is licensed under the MIT License - see the LICENSE file for details.