Android Mastermind

A native Android implementation of the Mastermind code-breaking game with configurable difficulty, game history persistence, and REST-backed gameplay features.

Introduction

This project is an Android application implementing the classic Mastermind game. Players attempt to discover a secret color code by making guesses and receiving feedback on the correctness of their selections. The implementation demonstrates core Android development patterns including activity-based UI architecture, SQLite persistence, REST API integration, and runtime-generated layouts.

The application features configurable game parameters (code length, available colors, and maximum attempts), real-time feedback calculation using the standard Mastermind scoring rules, and persistent storage of game history. Game data is sourced from a local REST backend, allowing for flexible content management and statistics tracking.

Features

• Configurable Gameplay: Adjust code length (2–6 positions), number of available colors (2–8), and maximum attempts (8–12)
• Game History: Persistent SQLite storage of all played games with email-based session tracking
• History Details: View past games with secret code, number of colors, result, and attempts used
• Real-Time Feedback: Immediate feedback on each guess indicating correct colors in correct positions and correct colors in wrong positions
• REST API Integration: Colors, secret codes, and game statistics sourced from a local JSON server
• Email-Gated Access: Home screen requires valid email input before game launch or configuration
• Multiple Outcomes: Win, lose, abandon, and new-game flows with appropriate UI dialogs

Tech Stack

• Language: Java
• Framework: Android SDK (minSdk 24, targetSdk 34)
• Build Tool: Gradle Kotlin DSL
• UI Libraries: AndroidX AppCompat, Material Components, ConstraintLayout
• Database: SQLite
• Networking: OkHttp, Jackson (JSON serialization)
• Testing: JUnit 4, Espresso

Architecture

The application follows an MVC-style layered architecture with clear separation of concerns:

• Activities Layer (activites/): Five main screens—home, configuration, gameplay, history list, and history detail
• Model/Core Layer (modele/core/): Game rules, feedback calculation, configuration management, and game state
• DAO Layer (dao/): SQLite game history and REST API communication via OkHttp
• UI Helper Layer (modele/ui/): Custom button components, dialog manager, and runtime layout builder
• Adapter Layer (adaptateur/): ListView and Spinner adapters for history and configuration UI
• Utility Layer (modele/utils/): Color manager and secret-code manager for API-backed resource loading

The game grid is dynamically generated at runtime based on configured parameters, with each row containing game buttons and feedback indicators.

Project Structure

Mastermind/
├── app/
│   ├── build.gradle.kts
│   ├── src/
│   │   ├── main/
│   │   │   ├── AndroidManifest.xml
│   │   │   ├── java/.../mastermind/
│   │   │   │   ├── activites/
│   │   │   │   │   ├── Accueil.java
│   │   │   │   │   ├── Configuration.java
│   │   │   │   │   ├── Jeu.java
│   │   │   │   │   ├── Historique.java
│   │   │   │   │   └── DetailActivity.java
│   │   │   │   ├── modele/
│   │   │   │   │   ├── core/
│   │   │   │   │   │   ├── GameController.java
│   │   │   │   │   │   ├── GameConfiguration.java
│   │   │   │   │   │   └── Feedback.java
│   │   │   │   │   ├── ui/
│   │   │   │   │   │   ├── ColorButton.java
│   │   │   │   │   │   ├── ColorPalette.java
│   │   │   │   │   │   ├── DialogManager.java
│   │   │   │   │   │   ├── FeedbackButton.java
│   │   │   │   │   │   ├── GameButton.java
│   │   │   │   │   │   └── LayoutManager.java
│   │   │   │   │   └── utils/
│   │   │   │   │       ├── ColorManager.java
│   │   │   │   │       └── SecretCodeManager.java
│   │   │   │   ├── dao/
│   │   │   │   │   ├── ApiRest.java
│   │   │   │   │   ├── GameHistoryDbHelper.java
│   │   │   │   │   ├── GameRecord.java
│   │   │   │   │   └── GameRecordsContract.java
│   │   │   │   └── adaptateur/
│   │   │   │       ├── ConfigurationSpinnerAdapter.java
│   │   │   │       └── HistoryAdapter.java
│   │   │   ├── res/
│   │   │   │   ├── layout/
│   │   │   │   ├── drawable/
│   │   │   │   ├── values/
│   │   │   │   ├── mipmap-*/
│   │   │   │   └── xml/
│   │   │   ├── test/
│   │   │   └── androidTest/
│   └── proguard-rules.pro
├── build.gradle.kts
├── settings.gradle.kts
├── gradlew
├── gradlew.bat
├── gradle/
├── mastermind.json
└── README.md

Setup and Installation

Prerequisites

• Android Studio 2022.1 or later
• Android SDK (API 24 and API 34+)
• Node.js and npm (for running the local JSON server)
• Java 8 or later

Step 1: Open the Project in Android Studio

1. Clone or open the repository in Android Studio
2. Allow Gradle synchronization to complete
3. Verify that the project builds without errors: Build → Make Project

Step 2: Launch an Android Emulator

1. Open the Virtual Device Manager (Tools → Virtual Device Manager)
2. Select or create an emulator with API level 24 or higher
3. Start the emulator and wait for it to fully boot

Step 3: Start the Local REST Backend

Open a terminal/PowerShell in the repository root and run:

# Run from the repository root
npx json-server --watch mastermind.json --port 3000

You should see output indicating the server is running on http://localhost:3000. The Android emulator will connect to this server via the special alias http://10.0.2.2:3000.

Step 4: Run the Android Application

1. In Android Studio, select the running emulator in the device dropdown
2. Press Run or select Run → Run 'app'
3. The application will launch on the emulator
4. Enter any valid email address on the home screen to proceed

Backend and API Dependency

This application requires a local REST backend running on port 3000. The backend is provided as a simple JSON server (json-server) configured with a mastermind.json data file.

Available Endpoints

• GET /couleursDisponibles: Returns list of available hex color codes
• GET /codesSecrets: Returns available secret codes with metadata
• GET /stats: Returns game statistics and previous game records

Emulator Networking

The Android emulator runs on a virtual machine and cannot directly access localhost. It uses a special host alias:

• Host machine: http://localhost:3000
• Android emulator: http://10.0.2.2:3000

The application automatically uses 10.0.2.2:3000 for all API calls when running in the emulator.

HTTP Configuration

Cleartext HTTP is explicitly enabled in AndroidManifest.xml for local development purposes. This is not suitable for production and should be replaced with HTTPS when deploying to a real backend.

Troubleshooting

"Failed to load colors"

Cause: The REST backend is not running or is unreachable.

Solution:

1. Verify that json-server is running on port 3000
2. Ensure you are running the command from the repository root where mastermind.json is located
3. Confirm the server is running at http://localhost:3000 by opening it in a browser
4. If running on a physical device, ensure your device and computer are on the same network and configure the API URL accordingly

Emulator Cannot Connect to Backend

Cause: The emulator is not using the correct host alias for reaching the local machine.

Solution:

• Verify the app is using http://10.0.2.2:3000 in ApiRest.java
• Ensure the backend is running before launching the app
• Restart the Android emulator if connection issues persist

"Connection refused" or "Unable to connect"

Cause: The JSON server may not be running from the correct directory.

Solution:

1. Ensure you are running the command from the repository root where mastermind.json is located
2. Verify that mastermind.json exists in the current directory
3. Check that port 3000 is not in use by another process

Testing

The project includes basic unit and instrumented test scaffolding:

• Unit Tests: app/src/test/java (JUnit 4)
• Instrumented Tests: app/src/androidTest/java (Espresso)

To run tests:

./gradlew test                # Run unit tests
./gradlew connectedAndroidTest # Run instrumented tests (requires emulator/device)

Screenshots

Home Screen

Game Configuration

Gameplay

Game Win

Game Loss

Game History

Contributions

This project originated as an academic mobile application project. The implementation and development work for this repository was completed independently by me.

Future Improvements

• UI Polish: Move hardcoded strings from layouts and code into strings.xml for better localization and maintainability
• Configuration Management: Extract hardcoded API URL into a configuration file or build variant
• Package Naming: Update package/application identifier for general-purpose distribution
• Debug Logging: Remove or gate debug output (e.g., secret code logging) for production builds
• Accessibility: Enhance color-blind accessibility with shape-based feedback indicators
• Error Handling: Improve resilience to network failures with retry logic and user-friendly error messages
• APK Distribution: Generate and document release APK builds for distribution

Development Notes

• The application uses Java 8 source/target compatibility
• The feedback algorithm follows standard Mastermind scoring rules
• Game history is persisted locally using SQLite