Lab 1: Silver Dollar Game¹

• Assigned: Monday, January 10
• Check-in Post: Before 9pm Thursday, January 13 (check-in forum)
• Due: 9pm Monday, January 17
• Collaboration: Partner assignment (groups of 2 people—you may also work alone)
• Handout: starter project
• Submit: Upload CoinStrip.java to Lab 1
• Reference:
  • Java Basics
  • OOP I
  • OOP II
  • Rock, Paper, Scissors example

Overview

In this lab, we will write a program to play the Silver Dollar Game described at the end of Bailey Chapter 3 (page 67). In addition to gaining experience writing, compiling, and running programs from scratch, this lab will help us to think about how we can efficiently represent data and break our logic into reusable methods. Careful planning will help tremendously, so take the time to complete the Preparatory Exercises before beginning your work on the lab.

Preparatory Exercises

Before you begin writing Java code for this lab, I recommend you (1) read the lab description from the textbook, (2) read through this lab handout, and (3) sketch out a design for your Silver Dollar Game program. You should feel free to use the sample Rock, Paper, Scissors Design Document as a guide. It is OK if the design is very simple to start! It is expected you will start with a rough outline and refine it as you work on the lab. You might also refer to this Rock, Paper, Scissors example that implements a simple Rock, Paper, Scissors game using the TwoPlayerGame interface that you will use for this lab.

Suggested Timeline

• Complete the Preparatory Exercises and Step 1: Getting the Code by Wednesday.
• Complete Step 2: Implementing CoinStrip by Friday
• That leaves you the weekend and Monday for Step 3: Testing, debugging, and Step 4: Style

Step 1: Getting the Code

Download the starter project (lab1-handout.zip). Unzip it and make sure the files are in their own folder. Open the folder in VS Code (File>Open Folder).

Step 2: Implementing CoinStrip

In this lab you will implement the Silver Dollar Game that is found at the end of Bailey Chapter 3 (Note: page 67 of the text, 83 in the PDF) or in this PDF excerpt.

As you think about the design of your game, you should first decide on a representation of the coin strip. Make sure your representation supports all of the operations necessary such as:

• Generating different game boards. Your game boards must conform to the following rules:
  • Each game board must have at least three coins, but the exact number of coins on a given game board must be chosen with some randomness.²
  • The locations of coins must be randomly selected. In other words, over the course of playing several games, you should expect to encounter different starting configurations.
  • No game should be “won” before it starts. In other words, there must be at least one legal move.
• Testing whether a move is legal. The rules are fully described in the textbook, but here is a summary:
  • No “going right”: Coins can only move to the left.
  • No “double occupancy”: At most one coin can occupy a space at a given time.
  • No “jumps”: Coins cannot pass another coin.
  • “Mandatory progress”: A coin must move one or more spaces.

• Printing the board. Somewhere in your code, you will call System.out.println, but we recommend using the following approach:

  Implement a public String toString() method for your CoinStrip class. It should return a reasonable String representation of the game board. This is where there we intentionally provide the least specification and give you the most flexibility. Your game board’s String representation should make it clear to the players exactly what the state of the game is at any given time. The string should also provide enough information to the player that they can specify the move that they would like to make next. However, you have some flexibility to add your own “style” to how you display the board. Simple is fine. Elaborate is fine. Please just make it clear!

• Testing for a win.

• Moving pieces. When a legal move is given, you should be able to adjust the state of the game to reflect that move. This includes things like relocating coins, changing the current player, etc.

When we say “representation,” our real focus is: what data structures will you use? For instance, you might use a variable boolean[10] board; to represent the game board, where each index of the array represents a space on the strip of paper, and true indicates that a coin is present in that space while false indicates that the space is empty. This is a sensible approach, but let’s think about the implications of this design:

• If I have a game with 3 coins, how large is my board array? What if I instead have 6 coins? In this representation, the size of the array is always larger than the number of coins, and the smallest size the board can be is the position of the rightmost coin.
• Let’s think about enforcing the rules. If I want to make sure a move doesn’t violate the “no jumps” rule, one approach is to check the starting position of the coin, and then examine every array index between that position and the target position of the coin after the move. If there is a true somewhere between those two locations, I know that my coin is “jumping” another. Given this implementation, how many locations do I need to check? The number depends on the “size” of my move.

There are other interesting design questions that would come up if we were to implement the Silver Dollar Game this way. Now, it is certainly possible to use this design to successfully create all the game’s required functionality, but it probably isn’t the best solution we can come up with. Let’s explore an alternative design.

The Two-Player Game Interface

The starter project provides a Java interface inside the file TwoPlayerGame.java. This interface describes three methods that you must implement in your CoinStrip class. We’ve replicated the contents of TwoPlayerGame.java below:

public interface TwoPlayerGame {

    /**
    * Returns true if the specification of a move describes a legal move
    * given the rules of the game. Note: this does not check whether the
    * move is a *good* move, only whether the move is legal.
    * The move specified is checked against all game rules.
    *
    * A move is described by:
    *   - a resource (e.g., position, gamepiece, pile of matches, etc.)
    *   - a description of the move (e.g., how many matches to remove, how
    *                                many spaces to move, etc.)
    * @param resource describes the game element
    * @param units describes the move
    * @return true if the move is valid
    */
    public boolean isValidMove(int resource, int units);

    /**
    * At the conclusion of this method, the game state is changed to represent
    * the completion of the described move. If the described move is not valid,
    * the behavior of this method is undefined.
    *
    *
    * A move is described by:
    *   - a resource (e.g., position, gamepiece, pile of matches, etc.)
    *   - a description of the move (e.g., how many matches to remove, how
    *                                many spaces to move, etc.).
    *
    * @param resource describes the game element
    * @param units describes the move
    */
    public void makeMove(int resource, int units);

    /**
    * Returns true if the game is over.
    * @return True if the game is over, false otherwise.
    */
    public boolean isGameOver();
}

Since we require that you use this interface, we’ll talk now about a design that we think lends itself to a nice implementation of the Silver Dollar Game.

Instead of representing the spaces on the game board, we can create a data structure that represents the locations of the coins. Let’s use an array of integers, int coins[], where each index corresponds to a single coin, and the value stored at a given index represents the location of that coin on the board.

Now let’s reexamine the questions we posed for the previous design:

• If I have a game with 3 coins, how large is my coins array? What if I instead have 6 coins? In this representation, the size of the array is always the number of coins. It does not change based upon where those coins are located.
• Let’s think about enforcing the rules. If I want to make sure a move doesn’t violate the “no jumps” rule, one approach is to check the starting position of the coin to be moved (examining the coins array at some index i), and then verifying that no coins lie between that location and the target position of the coin after the move. If I’m careful about my representation, I do not need to check every element of the array! Suppose I require that my coins array is in ascending order; how many “coins” do I need to check? Only one!

This is a very compact representation of the game, and it makes enforcing many rules fairly efficient!

Once you have worked through the details of your representation, write down the set of operations needed to adjust/check/populate your data structure (including operations you may need that are not in the TwoPlayerGame interface). Since we’re using Java, your representation should be hidden inside a class called CoinStrip. Operations are made possible by providing public methods that implement those operations. Think about what parameters your methods will take, what values they return, and what the methods do.

Required Methods

In addition to the TwoPlayerGame.java interface, we also require two methods to help us test your code. These methods are shown below:

/**
 * Returns the number of coins on the CoinStrip game board.
 * @return the number of coints on the CoinStrip game board.
 */
public int getNumCoins() {
    return 0;
}

/**
 * Returns the 0-indexed location of a specific coin. Coins are
 * also zero-indexed. So, if the CoinStrip had 3 coins, the coins
 * would be indexed 0, 1, or 2.
 * @param coinNum the 0-indexed coin number
 * @return the 0-indexed location of the specified coin on the CoinStrip
 */
public int getCoinPosition(int coinNum) {
    return 0;
}

I will rarely impose any particular implementation strategy on you in this course, and I don’t think these methods do so; the getNumCoins() and getCoinPosition(int coinNum) methods are quite general. In other words, the methods themselves ask you to provide specific behaviors (which we will rely upon to test your programs), but the methods do not impose any restrictions on the way you implement those behaviors. Further, we think the behaviors these methods provide is critical for any CoinStrip implementation that we can imagine, so we hope that you use these methods to simplify your code.

Further Details

The main method of your CoinStrip class should create a CoinStrip object and then prompt each of two players to make their moves. A move will be of the form:

<cn> <ns>

where <cn> (coin number) specifies the coin to be moved and <ns> (number of spaces) specifies the number of spaces that coin should be moved.

The program should prompt the user for another input if the move is illegal.

To read input from a terminal window, you can use Java’s Scanner class or StdIn from algs4. Here are links to the documentation for both:

• Scanner
• StdIn

In this case, I have provided a main method that runs the game and gets user input as part of the starter code.

Step 3: Testing

The lab handout includes some test cases to help you check whether your CoinStrip implementation follows the specification described in this writeup. The code for these test cases is located in CoinStripTest.java. Running this file with VS Code will run the tests, each of which will print out a message to the terminal about whether the test passed or failed. These tests check

• That the CoinStrip constructor
  • never creates a game that is already over (according to CoinStrip.isGameOver)
  • never creates a game where there is no valid move (according to CoinStrip.isValidMove)
  • never creates a game with fewer than 3 coins
  • randomly chooses the number of coins and their initial positions
• That CoinStrip.isValidMove correctly handles invalid moves

Passing these tests is part of your lab grade (see Grading). You are free to add test cases to CoinStripTests.java (this file is not turned in).

Some functionality of your game is most easily tested by playing your game in a methodical way. Make sure to play through a whole game, testing both valid and invalid inputs. You can assume the user will enter numerical inputs for the moves—it’s fine if your game crashes on other types of input.

Step 4: Style

As relatively new programmers, we are all developing our understanding of what it means to have good style. This is made difficult by the fact that the definition of good style is both hard to quantify, and hard to agree upon.

To help us all along our lifelong quests to write better code, we have included a tool inside each of our repositories that checks our code against some industry-standard, agreed-upon best practices. This tool is called checkstyle. The starter project is already configured to use checkstyle, and as part of Lab 0 you should have installed the Checkstyle for Java extension.

checkstyle will detect style problems, and underline them in red (errors) and yellow (warnings) in your code. They will also appear in the PROBLEMS tab in VS Code. You can view the PROBLEMS tab by going to View>Problems or pressing Ctrl-Shift-M (Cmd-Shift-M on Mac).

For this lab we will be fairly lenient on style grading, and become more strict later on in the course. You are expected to submit a CoinStrip.java that contains no checkstyle errors. In particular, you must fill out the header comment at the top of CoinStrip.java with your name, email, and a (brief) description of your code. You must also make sure to declare all fields of CoinStrip either public or private (probably private).

It is ok to have checkstyle warnings in your submitted code, though I encourage you to fix them if you have time. Avoiding these warnings will be part of your grade on future labs.

Grading

This lab will be graded out of 30 points as follows: