CSc 305 Project 3

Due Mon May 5 11:59 pm

The instructor has created a framework for graphical solitaire games such as Collapse.
GridGameFramework provides the graphical framework for games that are based on a two dimensional grid.
Developers create extensions or "plugins" for this framework that provide the game logic for a specific game.

View sample screenshots.

Framework Design

UML Class Diagram
Javadocs to the Grid Game Framework
Jar file with classes for the framework.


The main class is GridGameLoader who dynamically loads the plugin and initializes all the other components.
GridGUI is the graphical interface class that has a Swing Frame and components for the menu and board.
GridGUI will manage the placement of buttons, status panel, and the board.
GridGUI will create a grayscale background image from the background specified.
GridGUI will implement the behavior for displaying a scores list.

Creating a plugin

Each game ("plugin") will provide:

For each Button, the plugin specifies the label and the associated behavior. Buttons may be invisible in which case they are invoked via the key shortcut (E.g, "Alt-A" for "About").  (A plugin could have no buttons).

Each plugin is identified to the framework by a unique string identifier, for example "Hangman".  All the classes your provide must begin with this identifier (E.g., HangmanBoard, HangmanGame, etc.).

Game configuration options are stored in a file named "preferences.ini" that uses Windows ini file format.
Board background images are stored in Backgrounds/bkgd.jpg.

You must create a folder with the name of the plugin to store the resources the plugin needs:
In tree format, the needed directory hierarchy is:
GridGame (directory)
   + GridGameFramework.jar
   + ini4j.jar
   + Hangman*.class
   + Hangman (directory)
        + HighScores.txt
        + preferences.ini
        + Backgrounds (directory)
        |     + bkgd.jpg
        + PieceImages (directory)
              + *.jpg


Minesweeper

You will be implementing a version of Minesweeper to run as a plugin Grid Game.



The goal of Minesweeper is to find all the hidden bombs in a two dimensional grid. At the start of the game the grid is completely filled with hidden squares.  Click on a square to reveal the contents.  If you click on a square containing a bomb, you lose.  The goal is to uncover all the squares that don't contain a bomb as fast as possible.

When you click on an unoccupied square, numbers in squares next to unrevealed squares will indicate how many bombs are adjacent to it. For example, if an empty square has a 2 in it, there are 2 bombs adjacent to it.

When you click on an empty square that has no bombs next to it, all the adjacent empty squares are revealed.

A right mouse button click will toggle a "flag" image on and off. 

The status panel displays the number of squares remaining, moves made, squares revealed, and time elapsed. (You may label them whatever you like, and change the order if you prefer).
There are 5000 possible boards. The game begins with a randomly selected board.
The Restart button begins the same game over again.
New Game starts a different game (the next sequential game number).
Select Game lets you select a game by number.
Scores opens a dialog showing all the saved scores.

A hidden "About" button (Alt-A) shows the software version number and the current game number.
A hidden "Cheat" button (Alt-C) reveals the entire game board.
A hidden "Easy" button (Alt-E) creates a board with only one bomb in the upper left corner.

If the player wins the game a popup dialog should allow the player to save their time.


If the player loses, the squares are all revealed.

Resources

Required ini4j.jar file to read the preferences file:  [ini4j] - Java API for handling Windows ini file format

Minesweeper piece images:  MinesImages.zip  You may create your own images if you prefer.
Minesweeper background:  Minesbkgd.jpg


To run your plugin:
(Windows)  java -cp GGFramework.jar;ini4j.jar;. GridGameLoader Mines
(Unix)             java -cp GGFramework.jar:ini4j.jar:. GridGameLoader Mines

Here is a sample preferences.ini file you can use.

#Sample GridGame Properties File (for Minesweeper)

[Board Size]
small = 8
medium = 10
large = 12

[Difficulty]
easy = 1
moderate = 2
hard = 3



Assignment Submission

  1. Implement the classes for your plugin. Document your time and defects following the PSP script.  Write complete javadoc comments.
  2. Make sure your source code compiles with no errors and passes CheckStyle. (You're allowed 5 violations per 1000 lines of code.)
  3. Use handin to submit your source code electronically (see below).
  4. Print your source code using 10 point monospaced font.  You will have multiple classes; place the classes in alphabetical order.  Write your name at the top.
  5. Use the online PSP form submission. Staple your PSP forms on top, with the Summary Form on top.
  6. Submit your work to the table in front of the classroom at the next class meeting after the due date.

Handing in Your Source Code Electronically
       handin  graderjd  Project3  Minesweeper.zip
      

Scoring

Correct functionality  45%
Design and code quality 50%
Correctly completed PSP forms 5%


FAQ

Q: How do you determine the number of bombs to add to the map? I take it that it's based somehow off of the easy/medium/hard preference, but there is no set way in the instructions to determine this.
A: It's not important. Just invent some simple formula that incorporates difficulty factor and board size.

Q: How does one determine the player's Score that is seen in your screen shots?
A: Score is tiles removed.

Q: I'm getting an error I don't understand, because it appears that it happens in the framework code:
Exception in thread "main" java.lang.IllegalArgumentException: New row height less than 1
A: This error occurs when the framework is unable to find an image in the PieceImages folder. Usually this is because you have an file in the image directory that isn't really an image. It happened to one student who had a corrupted image download.
Another student discovered: "For whatever reason, when I make a folder in Windows (XP Pro) and add, say, 4 *.jpg's to it: Windows will actually put 5 files in there (I can't figure out what the 5th one is..). It's possible there is another program to blame ... My solution was to upload my PieceImages folder to hornet, then download them again and it was fine."

Q: I'm confused which cells should be revealed when I click on an empty cell.
A:This is not a crucial issue, so don't waste too much time with it.
By an "empty" cell, I mean one that has no adjacent bombs. When you click an empty cell, it recursively reveals all the other adjacent empty cells, until it gets to one that is numbered. For example, the screenshot below shows a board after only one move - clicking on the upper right corner (an "empty" cell).


Note that a click on a cell that contains a number does NOT perform this recursive reveal action.