(Most recent update: Mon, Nov 1 at 4:30pm. Look for red "Update:" tags.)

Objective

This homework will give you practice in manipulating one-dimensional arrays, and designing programs that use the MVC (Model-View-Controller) model of interaction.

Overview

For this homework you will implement a puzzle game called Jumble. In this game you are presented with a word whose letters have been permuted (e.g. "rotew") and the objective game is to unscramble the letters to determine the original word ("tower"). Your task in this program is to implement the class that controls the game, that is, the code that modifies the state of the game based on user input and detects when the word has been guessed. More details about the program are provided in the Specifications section. You may want to take a look at the Sample Run section before you read the detailed description.

This homework will be graded as follows:

• 90% - Implementation
• 10% - Time log

Specifications

You will write a program that lets a user play a simple word puzzle. The puzzle consists of a sequence of cells, each with a character. The goal of the game is for a user to unscramble a word, which has been selected and scrambled by your program. The game provides a set of unscrambling transformation, which the user can select from. Here is a short summary of the tasks your program must perform.

Summary of Program Tasks

1. The program picks a word from a dictionary. We will provide the dictionary.
2. The program then scrambles the word using a random set of transformations, which are described below.
3. The program displays the scrambled word and lets the user apply a sequence of transformations. The user wins the game when he/she manages to unscramble the letters, thus producing the original word. The sample run provides an example.

The user's goal is to generate the original word with a minimum number of transformation attempts. Note that your program does not need to solve the problem. It just controls the game, which the user is playing.

Transformations

Before you read these specifications, you should access the files associated with this homework by checking out the project named p5. The code distribution provides you with the following:

• Three Java files (PlayJumble.java, Jumble.java, PuzzleTests.java).
• A library called cmsc131PuzzleLib. (Don't confuse this with the cmsc131PictureLib).
• A text file dictionary.txt, which contains the words from which the game can pick. We will make a backup copy available on the class web page, in case you accidentally delete yours.
• A time log file.

Here is a description of each of these components.

Java Files

• PlayJumble - This class has a main method, which starts the game for you. You must not modify its contents.
• PuzzleTests - This class will allow you to tests different components of your program, without playing the game. You must not modify its contents.
• Jumble - You must implement this class, which controls the behavior of the game. We have provided a shell for this class where the methods you are expected to implement have basically empty bodies. By providing these methods you will be able to familiarize yourself with the GUI. This should help you during the development phase. You must modify/complete the provided methods and add any private utility methods needed in order to implement the game.

The Puzzle Library

The cmsc131PuzzleLib has the support classes you need for this homework. The classes you will find in this package are:

• PuzzleGUI - This class implements the graphical user interface.
• Puzzle - This interface defines the methods that the Jumble class must implement. Any class implementing this interface will be considered a puzzle, that is, a class that controls the state of the game.
• Random131 - This class implements a random number generator. For grading purposes we will need to control the random sequence. Therefore, you must use this class for random number generation, and not the Java library random number generators. The following static method is provided by this class. (You do not need to write it.)



int getRandomInteger(int maxValue);

This method returns a random integer in the range [0... maxValue - 1].



• Dictionary131 - This class implements a simple dictionary. The dictionary relies on the text file dictionary.txt (which is part of the code distribution). The following static method is provided by this class. (You do not need to write it.)



String getRandomWord(int maxNumberOfLetters);

This method returns a random word from the dictionary whose length (number of characters) is not greater than the parameter maxNumberOfLetters.

Your Assignment

Your assignment is to implement the Jumble class. (Everything else is provided.) Because we have provided the GUI you do not need to perform any input or output (e.g., using JOptionPane). Before you implement the Jumble class methods you should familiarize yourself with the GUI.

Interacting with the GUI

Before discussing what you need to do, we explain how your program interacts with the GUI to play the game. The GUI is provided in the class PuzzleGUI, which we have implemented. The GUI does all the work of interacting with the user and displaying the images. It calls methods in your Jumble class to perform the actual transformations, which define the game's behavior. You implement these transformations. The relationship is shown in the figure below. (We will explain the meaning of generatePuzzle, getContents, etc. below.)

To see how the GUI operates, bring up Eclipse, download the distribution, and execute the main method of the PlayJumble class. The Jumble class provided as part of your code distribution defines some minimal functionality, but it does not actually play the game. However, each method in the class prints a message, so you can see when these methods are being invoked. You must remove these print statements before submitting your homework.

The PuzzleGUI class relies on the Jumble class to implement the game's behavior. When the user clicks on cells in the puzzle, the GUI calls the appropriate methods from the Jumble class in order to perform the required processing. For example, when the user wants to swap two characters, he/she clicks on the two cells to be swapped, the GUI identifies the cells that are clicked (and changes the color) and then calls the method cellsSelected() from your Jumble class to perform the actual swap transformation on an array. The array is stored as an instance variable within the Jumble class.

When you run the main method of the PlayJumble class. On the screen it will first ask for the number of characters and number of transformations. Type in two numbers, say 7 and 2. You will then see a window containing the word "NOTREADY". You will also see messages printed to the console indicating which methods of the Jumble class have been called. We will discuss these below. Experiment by clicking on pairs of cells (also while holding the SHIFT or CTRL keys down) and observe the messages produced in the console below.

The three transformations (swap, move, bump) are activated as follows. To request an transformation, the user clicks on two cells. Let these be at positions i and j. (Positions are indexed starting with 0 at the left end.) The actual operation depends on the combination of SHIFT/CTRL keys that are held down.

• Holds down no keys: swap(i, j)
• Holds down SHIFT key: move(i, j)
• Holds down CTRL key: bump(i, j)

Recall the above descriptions of these transformations. Of course, nothing will happen until you have implemented the methods of the Jumble class, which we describe in the next section.

If you want to stop the game at any time, just close the puzzle window. You will see a message to the effect that the game has not been solved.

Jumble Class Implementation

The Jumble class must implement the Puzzle interface. The following are the specifications associated with this class:

Instance Variables

You may decide the type and number of instance variables you will need for this class. At a minimum, you will need to store the set of characters in the original (unscrambled) solution word as well as the characters in the (partially scrambled) current word. You must use two character arrays for storing these.

(Update: The following added, Sat, Oct 30 at 8:30pm.)

Except for instance variables that are constant (static final), all instance variables in class Jumble must be nonstatic and must be explicitly initialized in the method generatePuzzle (described below). This is required for our testing software to run correctly.

Required Public Methods

Take a look at the file Jumble.javaas you go over the description of the following methods. Feel free to add any private methods you understand can simplify the implementation process. However you may not add any public methods. Remember that avoiding code duplication is important and defining private methods can help you accomplish this goal.

• generatePuzzle: This method is called by the GUI in order to set up the initial scrambled word. Because it is more complex than the others, it is described in detail below.
• getSolution: This method returns the solution to the game (the original word returned from the dictionary), represented as an array of Strings. Each element of the array is one character of the solution. This method has the following signature.
  public String[] getSolution();

(Update: return type fixed, Wed, Oct 27 at 9:00pm.)

• getSolutionLength: This method returns the number of characters in the solution. This method has the following signature.
  public int getSolutionLength();

• getContents: This method returns a String array where each entry of the array is the String representation of the corresponding character in current word. The GUI uses this method to determine what it should draw. This method has the following signature.
  public String[] getContents();

• cellsSelected: This method is called by the GUI whenever the user has clicked on two cells. This method has the following signature.
  public void cellsSelected(int firstLetterIndex, int secondLetterIndex, int transformation);

  The first parameter is the index iof the first cell selected, the second parameter is the index jof the second cell selected, and the third parameter indicates the desired transformation. The third parameter is either 0 for swap, 1 for move, and 2 for bump. For example, the call cellsSelected(3, 9, 2) means that desired transformation is bump(3, 9).

• isSolutionCorrect:
This boolean method returns true if the current word equals the solution word, and false otherwise. This method has the following signature.
public boolean isSolutionCorrect();
• getNumOfInitTransformations: This method returns the initial number of random transformations used to generate the scrambled word. It is used for the final message at the end of the game. It has the following signature.
  public int getNumOfInitTransformations();

• getAttempts: For scoring purposes, the Jumble class must keep track of the number of transformations that the user has made in attempting to solve the puzzle. Each call to the cellsSelected() method represents one attempt. This method returns this number. It has the following signature.
  public int getAttempts();

The generatePuzzle Method

1. Generate a random integer r in the range [0...2] (using Random131.getRandomInteger()). Depending on its value the transformation to be applied will be either swap (r=0), move (r=1), and bump (r=2), respectively.
2. Select a random integer i in the range [0...size-1], where size is the length of the selected word to be scrambled.
3. Select another random integer j in the range [0...size-1]. (Note that i and j may be equal. This is okay.)
4. Apply the transformation (as determined in the first step) to the cells at positions i and j. For example, if the first three random numbers had been r=1, i=4, j=7, then you would perform the transformation move(4, 7).
5. Repeat the above steps until the requested number of transformations (numTransformations) have been performed.

Notes

• If numTransformations is 0, no transformations are performend and the original word is unchanged.
• The parameter numTransformations indicates the number of random transformations to be performed, not which particular transformation is performed.
• All random numbers must be generated using Random131.getRandomInteger(), and not Java's built-in random number facilities.

Requirements

• As with all programming assignments:
  • You must use meaningful variable names and good indentation.
  • You must avoid code duplication, by calling appropriate methods (rather than cutting and pasting code). You may define your own private utility methods to perform often repeated tasks.
  • Because we are now using an automatic testing system, it is important the you adhere closely to the specifications. In particular, please do not change the names of any of the classes you are to implement, and use signatures given above for your methods.
  • Try your best to use the Eclipse/CVS submit option for your submission. If you are having problems with this, please contact us. Use the submit server only as a last resort for submitting your program. If you find it necessary to use the submit server, please see the following page for information on jar creation for submission.
  Because of the difficulty in grading emailed submissions, we will start deducting points unless you submit via the submit option or the submit server.
• You must use character arrays for storing the current word and solution word in your Jumble class.
• You must use Random131.getRandomInteger(), and not Java's built-in random number generator, for all random numbers.
• You must remove the print statements, which we provided, in the original Jumble.java.
• To have confidence that your classes have been implemented correctly, execute it using the provided driver (PlayJumble.java). Of course, you should also perform your own testing to be sure.
• Submit your project even if you are not able to complete all the functions. You will receive partial credit, for example, if your program swaps, even if it cannot perform the move or bump transformations.

Sample Run

Here is an example of playing the game (PlayJumble.java) with 5 as the maximum number of letters and with 2 initial transformations. Because the words are generated randomly, your initial random word will likely be different when you play.

After starting the game and entering 5

After pressing OK and entering 2

After pressing OK and selecting letter h

After selecting letter e (thus invoking swap(1,3))

After holding down SHIFT key while selecting letter e

Still holding down the SHIFT key while selecting letter s (thus invoking move(1, 4))

After releasing SHIFT key, and then holding down the CTRL key while selecting letter u

Still holding down the CTRL key while selecting letter e (thus invoking bump(1, 4))

After releasing the CTRL key and selecting s and o (thus invoking swap(1, 3))

After selecting e and u (thus invoking swap(2, 4))

At this point the puzzle has been solved. After pressing OK the game ends.

Testing Using PuzzleTests

To provide you with additional confidence that your program works correctly, we have provided a special class for testing purposes, called PuzzleTests. Executing the main method of the class PuzzleTests will allow you to test some of the functionality expected from the Jumble class. There are five tests:

• swap transformation test
• insert transformation test
• bump transformation test
• generation of random puzzle test
• a general test

Each test can be selected through the appropriate menu entry. The results for each test can be found in the following files: Test1ResultsSwap.txt, Test2ResultsMove.txt, Test3ResultsBump.txt, Test4ResultsRandomPuzzle.txt, Test5ResultsJumble.txt. (Update: The file names fixed. Wed, Oct 27 at 9:00pm.)

Challenge Problem

Remember that you are not required to implement the following problem. Please visit the course web page for information regarding challenge problems. IMPORTANT: If you decide to complete the challenge problem you must provide its implementation in the file called Challenge.java. The Challenge class defines a modified Jumble class which implements the challenge problem. Make sure you don't modify the main method we have provided in the Challenge.java file.

For this challenge problem, replace the bump transformation (when two cells are clicked with the CTRL key held down) with the following new transformation.

sort(i, j):

This transformation is given two positions i and j and sorts the characters from position i to position j (inclusive). If i < j then the values are sorted in increasing order and if i > j the values are sorted in decreasing order. Note that sort(i, i) has no effect on the word.

For example, if the word was "musicality" the operation sort(1,8) would sort the characters from 'u' to 't' (namely 'u', 's', 'i', 'c', 'a', 'l', 'i', 't') in ascending order, resulting in the word "maciilstuy". On the other hand, if we started with the original word, the operation sort(3,0) would sort the first 4 characters in descending order, resulting in the new word "usmicality". (Update: The preceding example was fixed Mon, Nov 1 at 4:30pm.)

Submission

Submit your project using the submit project option associated with Eclipse. Remember to complete your time log before submitting your homework.