BlockDoku Puzzle Game (Java)

This project is a Java implementation of a Blocks Puzzle game inspired by Sudoku style region clearing mechanics. The game was developed as part of an object oriented programming assignment and then extended with additional features beyond the core requirements.

The project follows a Model View Controller architecture and emphasises clean separation of concerns, testability, and extensibility.

Overview

The game is played on a 9 by 9 grid divided into 3 by 3 sub regions. The player is given a set of polyomino shapes which can be dragged and dropped onto the grid. When a full row, column, or sub region is completed, it is cleared and points are awarded.

The game ends when none of the available shapes can be placed on the grid.

Architecture

The system is structured using the Model View Controller design pattern.

1. Model
   The model layer contains all game rules and logic, including placement validation, region detection, clearing logic, scoring, and game over detection. The model is completely independent of the graphical user interface.

Two interchangeable model implementations are provided.

Model2dArray uses a two dimensional boolean array representation. ModelSet uses a HashSet based representation for occupied cells.

Both implementations conform to a shared ModelInterface, allowing them to be swapped without affecting the controller or view.

2. View
   The view layer is responsible for rendering the grid, shapes, highlights, streak indicators, and overlays such as the leaderboard. It does not modify game state directly.

3. Controller
   The controller handles user input, including mouse press, drag, and release events. It converts screen coordinates into grid coordinates, queries the model for placement validity, updates game state, and triggers view repaints.

Gameplay Features

The core gameplay includes drag and drop placement, ghost previews for valid placements, region highlighting before clears, and automatic detection of game over conditions.

Several extensions were implemented beyond the base requirements.

Score Streak System
Consecutive clears increase a streak multiplier which boosts scoring. Placing a shape that clears no regions resets the streak.

Bot Player
An optional automated bot can play the game by searching for valid placements and placing pieces programmatically. The bot uses the same model API as the human player and is useful for testing and demonstration.

Leaderboard
A persistent leaderboard stores the top scores along with player names and maximum streaks. Scores are saved to a text file and displayed as an overlay within the game.

Code Organisation

The project is organised into multiple classes with focused responsibilities, including separate classes for the controller, view, models, palette handling, bot logic, leaderboard persistence, and region detection helpers.

This structure makes the codebase easier to maintain, test, and extend.

Notes

This project was originally developed as a university assignment with a provided scaffold. All core logic was implemented to complete the assignment, and additional features such as the streak system, bot player, and leaderboard were designed and implemented independently.