Project 1
Minesweeper

Muddiest Points Due: Thu 2/29 at 10pm
Pseudocode Due: Mon 3/4 at noon
Project Due: Fri 3/15 at noon

Introduction

The programming projects are an opportunity for you to work on a larger program, where there are more pieces to bring together. Unlike the labs, you have several weeks to complete this project — but this project is larger than the lab programs, so start early! There will not be a new lab assignment on 3/12 so there will be time during lab to work on the project, but this is only a few days before it is due so you should not wait until then to get started.

Collaboration

Labs and projects are for practice and learning. While it can be very productive to work on problems with your peers, it is also easy to underestimate how much you yourself understand and can do in such situations — so often something looks easy when someone else does it! With this in mind, you should always make the first attempt on a problem or programming task yourself using only the resources provided for the course (textbook, slides and examples posted on the schedule page, other resources linked on the course webpages). After that point, you are encouraged to come to office hours and/or go to Teaching Fellows. You may not collaboratively write solutions or code, and you may not copy solutions or code written by others, even if you contributed ideas.

You can discuss specific exercises with other students in general terms — such as how you might get started on that problem, or how or when to use various programming constructs, or strategies for debugging — but how to use a particular programming construct to solve a specific problem or debugging a particular program should only be discussed in office hours or with the Teaching Fellows.

Setup

Remember that you will need to compile and run your program(s) using jfxc and jfx, respectively, instead of javac and java.

Overview and Requirements

In this project you will be writing a somewhat simplified version of the Minesweeper game. The object of Minesweeper is to identify the mines hidden in a grid of squares — if the player uncovers a square with a mine, the game is over; otherwise, the number of mines in adjacent squares is revealed. The player can then use this information to deduce the locations of the mines. See the Wikipedia entry on Minesweeper for more information on the game.

Compared to the real game, your program will have several simplifications:

• No mouse: Instead of clicking on a square to uncover it, the player will use the arrow keys on keyboard to move left, right, up, and down. This means the player is always positioned at some particular square. The current square can be uncovered by pressing the space bar.

• No flags: The player has to remember which squares she suspects have mines — there's no mechanism for marking them with a flag. (Extra credit option!)

• One game: Once the player wins or loses, she must close the window and run the program again to play another game.

• No auto-uncover: When the player uncovers a square with a count of 0 (i.e. there are no adjacent bombs), neighboring squares are not automatically uncovered. (Extra credit option!)

To see how your program should work, try out the demo: (type the commandline in the terminal in VS Code)

  jfx -jar /classes/cs124/demos/minesweeper.jar

Move the yellow square (the current position) using the arrow keys (make sure the mouse is within the program's window before you start pressing keys); press the space bar to uncover the square at the current position.

Program Specifications

Your task is to write a game of Minesweeper that works like the demo — the player moves the current position around, uncovering squares until either all of the squares without a mine have been uncovered or a mine is uncovered. Some specific details:

• The grid should be 10 rows by 20 columns.

• There should be 40 hidden mines, placed randomly on the board. (A square can contain at most one mine, so you should be careful not to put a mine in a square that already has one when you are distributing the mines.)

• The player should move the current square using the arrow keys.

• Pressing the space bar should uncover the current square, revealing the number of mines adjacent to the square if it isn't a mine.

• The game should end if the player uncovers a mine (the player loses) or if the player has uncovered all of the squares not containing a mine (the player wins).

You are free to customize the program's graphics (colors, fonts, etc) as long as the following are met:

• The board squares are large enough to see but the drawing window still fits on the screen. (Each square in the demo is 30 pixels by 30 pixels.)

• The grid should be apparent. (The demo draws a black line around each square.)

• The current square is distinguishable from the other squares. (The demo colors it yellow.)

• The uncovered squares are distinguishable from still-covered squares. (The demo colors uncovered squares cyan (light blue) and still-covered squares light gray.)

• If an uncovered square contains a mine, there should be some symbol drawn indicating this. (The demo draws a simple bomb icon.) If an uncovered square doesn't contain a mine, the count of neighboring squares with mines should be displayed.

• If the player loses (by uncovering a mine), the entire board should be displayed as if all the squares have been uncovered. In addition, text should appear in the drawing window that says something to the effect of "You lose!".

• If the player wins (by uncovering all of the squares not containing a mine), text should appear in the drawing window that says something to the effect of "You win!".

You should also make sure that your program doesn't crash or behave badly if the user does something unexpected. This includes making sure that the current position doesn't move past the boundaries of the board — for example, if the current position is in column 0, pressing the left arrow should have no effect.

Implementation

To keep track of the necessary information in order to play the game, you will need to have several variables:

• a 2D array storing whether or not each square has been uncovered
• a 2D array storing whether or not a square contains a mine
• a 2D array storing the number of adjacent mines for each square
• the row and column of the player's current position on the board

Each of the 2D arrays should have 10 rows and 20 columns.

(You may need additional variables for loops or other things.)

Programming Style

As with labs, you should follow the standard conventions for indentation, line breaks, naming, and comments. Using autoformat will take care of most of the formatting considerations, though you still need to put in blank lines yourself in order to visually group related statements together and separate statements dealing with separate tasks. Remember to include enough in your variable names to identify what they are for and to distinguish similar variables each other, and to comment your variable declarations if there is additional relevant information not apparent from the variable name.

In addition, you should include comments identifying what is accomplished by chunks of code. (If you write your code under the relevant pseudocode comments that you develop for the pseudocode exercises, you'll have this taken care of.) This isn't about explaining every single line of code, but rather making it easier to get an overview of your program and to understand the tasks that different groups of statements are accomplishing.

Your code should be reasonably compact and elegant, meaning that your program is not significantly longer or more complex than it needs to be. One important component of this is that you use loops when loops are appropriate — achieiving repetition by copying-and-pasting code is not elegant!

Extra Credit

There are lots of possibilities for extra credit — start early so you have time to try some of them! Some possibilities include:

• [small] Use named constants for the grid width, grid height, and number of mines so that you can change one of the values by changing just one number in the program. You can read more about constants in section 4.8.3 though it should be noted that all of the examples in that section are of static constants (declared outside main or another subroutine). You should declare your constants inside draw (along with all of the rest of your code), which means leaving out the words public and static.

• [small] Use subroutines to better organize the program and make it easier to understand. The amount of extra credit will depend on how appropriate your choices are.

• [small] Allow the user to play more than one game, and keep track of the user's best score. (The score is the number of squares successfully uncovered.) Display both the best score so far and the score for the current game at the end of each game.

• [small/medium] Improve the game graphics. The amount of extra credit will depend on how much effort you put into this — more significant or sophisticated changes to the look of the game will earn more extra credit; minor changes (such as choosing different colors) will not earn any.

• [medium] Allow the player to flag squares thought to contain mines. Pressing 'f' should toggle the flag — if there's no flag, pressing 'f' adds a flag; if there is a flag, pressing 'f' should remove it. If a square contains a flag, a little picture of a flag should be drawn in that square.

• [large] Add the "auto uncover" feature. This means that when the player uncovers a square with a mine count of 0, the program automatically uncovers all of the adjacent squares. If any of those squares have a bomb count of 0, the neighbors of those squares are also uncovered, continuing until every square adjacent to a non-visited square has a bomb count greater than 0. This is worth a significant amount of extra credit, but be warned: this is challenging!

The tags "small", "medium", and "large" are meant to give some idea of the level of effort involved. (The "large" items are significantly more work.) More involved options and more elegant solutions will earn more extra credit. (The chief things to be concerned about are unnecessarily complex solutions, and unnecessary repeated code.) A maximum of 15 points (out of 100 for the project) of extra credit can be earned. If you plan to tackle a lot of extra credit or have an idea for something not listed, come discuss your plans with me.

Exercises

Work through these in order.

Muddiest Points

Stepwise Refinement and Pseudocode

This is a larger program with a number of different components, so it is important to make sure you have a plan before you start writing code. Use the program development strategy that has been discussed in class (and which you have been using in the labs) — write out broad steps in English, then a bit at a time transform those steps into smaller steps with program-like structures (the order of steps should be clear, and use language associated with the making choices and repetition patterns discussed in class). To get you started, here's the first very broad level of pseudocode:

// set up the game
// play the game

"Set up the game" covers everything that needs to be done before the player starts playing — if you think of the demo, it covers everything that happens before you press a key for the first time. Properly initializing the variables in the program is a major part of the setup. (See the "Implementation" section above for important variables that you will need to have.) "Play the game" covers everything once the user starts pressing keys. Between the two steps, the entire program's functionality is covered.

Now, proceed with stepwise refinement — for each broad step, think about what it entails in a little more detail. Also identify what the main flow of control is within that step — does it involve a series of smaller steps, or repetition, or making a choice? That should then be reflected in the structure of your pseudocode, for example:

// set up the game

// play the game
// -- repeat until the game is over
// -- .. get the user's key press
// -- .. handle the user's key press
// -- display win or lose message

(Because you will eventually transfer this to your program and autoformat takes out extra spaces, keep things organized by adding dashes to visually indicate when things are substeps of larger tasks and dots to indicate containment within control structures (loop bodies, bodies of if branches).)

At each step, check for the key elements of pseudocode:

• Pseudocode contains the steps to be carried out — it describes the algorithm. It is not a to-do list of things the programmer needs to do in writing the program or a list of notes or rules to keep in mind while performing the task. (Incorporate those notes or rules into the process of how the task is carried out.)

• Pseudocode has complete coverage — only details about how to carry out steps are missing, not the steps themselves.

• Pseudocode has the structure and flow of the program — the order of the steps is clear, and constructs that translate easily to code are used to define this order. For loops in particular, make sure there is a clearly identified body.

Continue breaking down tasks until they are small enough. This is a bit vague, and there isn't a firm right or wrong answer, but the idea is that you've gotten down to specific and self-contained tasks which are straightforward to translate into Java because they utilize a common or familiar pattern or would only take a few lines of code.

Technical Details — Drawing and User Input

You can draw the game board by going through each slot of the 10x20 grid and drawing the corresponding square in the drawing window — use the information stored in that slot in each of the two arrays to determine how to draw the square (covered or uncovered, number of mines or bomb). You can use fillRect to draw the square (and strokeRect to draw an outline around it, to distinguish one square from another), however, you will need to know the position of the upper left corner of each rectangle in order to draw it. You can work out a formula for converting from the row and column of the grid cell to the y and x coordinates for the rectangle (keep in mind that the x coordinate corresponds to the column and the y coordinate corresponds to the row — this is easy to mix up!), but a simpler option is to treat both the row and column of the grid cell and the x and y coordinates of the rectangle as things that change in the loops and initialize/update them accordingly. (The ColorSpots example from class illustrates this — i is the counter going through the array indexes and x is the x coordinate for the current oval.)

Your program will need to repeatedly get input specifying the player's next move. Since this is a graphical program, you won't use Scanner; instead, the provided Minesweeper template includes getKeyCode() to support getting the user's key presses. (Normally GUIs utilize what is known as event-driven programming, but that is beyond the scope of this course, so getKeyCode() is a workaround.)

Like the Scanner operations, call getKeyCode() when you want user input; it will wait until a key is pressed and then return a value indicating which key was the one pressed. As with Scanner, you'll probably want to store that value in a variable so you can work with it:

  KeyCode key = getKeyCode();

Then, to determine what key was pressed:

  if ( key == KeyCode.LEFT ) {     // left arrow pressed
    ...
  }

Checking for the other possibilities (KeyCode.RIGHT, KeyCode.UP, KeyCode.DOWN, or KeyCode.SPACE) is similiar.

(If you do the "flag" option for extra credit, you'll need to check another key: KeyCode.F)

Finally, Minesweeper

Hint: The game board changes as the user plays the game — the current position moves, squares are uncovered, etc. There are a couple of ways to handle this, but the easiest is to just redraw the entire board each time there is a change. (This is a better strategy than trying to redraw just the parts that have changed.)

Handin and Grading

Don't forget to hand in your work when you are done!

As with labs, grading will be based on both functionality and style. The expectations for both are given in the "Overview and Specifications" section above.