Com S 227 Spring 2017 Assignment 3 300 points Due Date:, Wednesday, March 29 11:59 pm (midnight) Late deadline (25% penalty): Thursday, March 30, 11:59 pm General information This assignment is to be done on your own. See the Academic Dishonesty policy in the syllabus, http://www.cs.iastate.edu/~cs227/syllabus.html, for details. You will not be able to submit your work unless you have completed the Academic Dishonesty policy acknowledgement on the Homework page on Blackboard. Please do this right away. If you need help, see your instructor or one of the TAs. Lots of help is also available through the Piazza discussions. Our second exam is Monday, April 3. Note that it will not be possible to get all the homework submissions graded before the exam. Please start the assignment as soon as possible and get your questions answered right away! Introduction You will be writing the logic for a version of a video game generally known as "Flow Free". You'll get lots of practice working with arrays, ArrayLists, and files. Once you have your code working, you'll be able to integrate it with a GUI that we have provided to create a complete application. Your task will specifically be to implement the two classes FlowGame and Util.
The game is typically viewed as a grid in which pairs of cells are marked with the same color. A mouse or pointing device is then used to connect the matching pairs. The lines between matching pairs cannot cross, and must eventually occupy all cells. For example, here is a simple grid as viewed in the sample GUI: Figure 1 The abstractions we will use for representing the game state are two simple classes called Cell and Flow, located in the api package of the sample code. (These two classes are fully implemented and you should not modify them.) A Cell represents a row, column, and color. (We will use the library class java.awt.color to represent colors.) A Flow represents a sequence of cells that may (eventually) connect the two matching endpoints. Thus a Flow object encapsulates the following: two Cell objects representing the matching endpoints to be connected an ArrayList of Cell objects representing the sequence of cells in the flow The two endpoints are always present in the object, but are not necessarily in the list. The list is initially empty, and may grow (or become empty again) based on user actions. The two endpoints are in no particular order.
Game state Overall the complete state of the game consists of a width and height, an array of Flow objects, and a designated "current" cell. Intuitively, the "current" cell corresponds to the current mouse or pointer position. It can be null when nothing is currently being selected. Basic operations The basic operations on the game are startflow(row, col), endflow(row, col), and addcell(row, col). The startflow operation sets the current cell. When using a GUI, it is typically invoked when the mouse is pressed. There are restrictions on which cells can be selected by a startflow operation: Any endpoint can be selected as the current cell. Selecting an endpoint clears the flow associated with that endpoint and then adds the cell to the flow. A non-endpoint cell can be selected as the current cell only if it is the last cell in a flow. For example, the end of the green line seen in row 4, column 3 of Figure 1, represents the last cell of a flow, so it can be selected as the current cell. The addcell operation attempts to add a new cell to the flow containing the current cell. When using a GUI, it is typically invoked when the mouse is dragged. The restrictions are: 1. The current cell is non-null 2. The given position is horizontally or vertically adjacent to the current cell 3. The given position either is not occupied OR it is occupied by the matching endpoint for the flow If the three conditions are met, a new cell with the given row/column and correct color is added to the current flow. If the added cell is not an endpoint, it becomes the current cell. If the added cell is the second endpoint, the current cell becomes null. The endflow operation basically just sets the current cell to null. When using a GUI, it is typically invoked when the mouse is released. Detailed specification The sample code includes a fully documented skeleton of FlowGame.java. and Util.java. Read the javadoc comments for details about the precise behavior of methods. You can also find
all the documentation online at: http://web.cs.iastate.edu/~cs227/homework/hw3/doc/ There are also some usage examples later in this document in the "Getting started" section. The Util class You will also be implementing a class called Util that can be used to construct games from string descriptions or by reading from a file. This is a "utility" class containing only static methods. We can represent an initial game state with an array of strings in which all strings are the same length and can be interpreted as a grid. Here is an example: String[] testgrid = { "GR-R", "--GB", "B---" }; Letters show the positions and colors of the endpoints, and the other characters represent empty cells. The correspondence between letters and colors can be seen in the code for the Cell class. A game constructed according to the string descriptor above would look like this: Figure 2
One of the methods of the Util class you will write takes a string descriptor and returns an array of Flow objects constructed from it. The other method of the Util class takes a filename and returns a list of one or more FlowGame objects. The idea is that the file contains groups of lines similar to the string descriptor shown above. Each group is separated from the others by one or more blank lines (a "blank line" is some amount of whitespace including a newline character). For example, here is a sample text file containing descriptors for three different games: ------ -OR-G- BG-OR- ------ B----- GR-R --GB B--- R---------Y OB--------G ----------M S--------G- --VP-O----- -P--------- ----CS-B--- --M----FR-- ----Y------ ---------F- VC--------- (The third one was downloaded from http://playplayfun.com/flow-free/play/) As long as you stick to the eleven allowable letters, you do not have to worry too much about the class java.awt.color that is used to represent colors. If you just pass the character to the Cell constructor, it will assign that cell the corresponding color. To check whether a color matches a cell's color, you can use the Cell method colormatches. (To compare two Color objects directly, use.equals().) Importing the sample code The sample code includes a complete skeleton of the two classes you are writing. It is distributed as a complete Eclipse project that you can import. It should compile without errors
out of the box. However the GUI will not run correctly until you have implemented the basic functionality of FlowGame. Basic instructions for importing: 1. Download the zip file to a location outside your workspace. You don t need to unzip it. 2. In Eclipse, go to File -> Import -> General -> Existing Projects into Workspace, click Next. 3. Click the radio button for Select archive file. 4. Browse to the zip file you downloaded and click Finish. Alternate procedure: If you have an older version of Java (below 8) or if for some reason you have problems with this process, or if the project does not build correctly, you can construct the project manually as follows: 1. Unzip the zip file containing the sample code. 2. In Windows File Explorer or OS X Finder, browse to the src directory of the zip file contents 3. Create a new empty project in Eclipse 4. In the Package Explorer, navigate to the src folder of the new project. 5. Drag the hw3, ui, and api folders from Explorer/Finder into the src folder in Eclipse. The GUI The sample code includes a GUI in the ui package. The main method is in ui.gamemain. You can try running it, and you ll see the initial window, but until you start implementing the required classes you ll just get errors (see the getting started section for more details). The GUI is built on the Java Swing libraries. This code is complex and specialized, and is somewhat outside the scope of the course. You are not expected to be able to read and understand it, though you might be interested in exploring how it works. It's important to realize that the GUI contains no actual logic or data for the game. At all times, it simply displays the information returned by your getallflows() method, using the values of your getwidth() and getheight() methods for the size. It invokes the startflow method when the user presses the mouse; it invokes the endflow method when the user releases the mouse, and invokes the addcell method when the user drags the mouse. It stops the timer and ends the game when your iscomplete method returns true. So if something's not working, go back to your FlowGame class and write some more unit tests!
All that the main class GameMain does is to initialize the components and start up the UI machinery. The class GamePanel contains most of the UI code and defines the "main" panel, and there is also a much simpler class ScorePanel that contains the display of the score. You can configure the game by setting editing the create() method of GameMain; see the comments there for examples. You may also notice the button "Choose from file" at the top of the UI. When your Util class is done and debugged, you can try it. It should bring up a file dialog and allow you to select a file. It will then attempt to read your file and obtain the list of FlowGame objects returned by the Util.readFile method. It then brings up a dialog with a drop-down list allowing you to select one of the games that was found in the file. (Optional reading) If you are curious about what s going on, you might start by looking at the method paintcomponent in GamePanel, where you can see the accessor methods such as getallflows being called to decide how to "draw" the panel. The most interesting part of any graphical UI is in the callback methods. These are the methods invoked when an event occurs, such as the user pressing a button or a timer firing. You could take a look at MyMouseListener.mousePressed and MyMouseMotionListener.mouseDragged in which you can see the calls to your startflow and addcell methods. (These are inner classes of GamePanel, a concept we have not seen yet, but it means they can access the GamePanel's instance variables.) If you are interested in learning more, there is a collection of simple Swing examples linked on Steve s website. See http://www.cs.iastate.edu/~smkautz/ and look under Other Stuff. The absolute best comprehensive reference on Swing is the official tutorial from Oracle, http://docs.oracle.com/javase/tutorial/uiswing/toc.html. A large proportion of other Swing tutorials found online are out-of-date and often wrong. Testing and the SpecChecker As always, you should try to work incrementally and write simple tests for your code as you develop it. Do not rely on the GUI code for testing! Trying to test your code using a GUI is very slow, unreliable, and generally frustrating. In particular, when we grade your work we are NOT going to run the GUI, we are going to verify that each method works according to its specification. Since test code that you write is not a required part of this assignment and does not need to be turned in, you are welcome to post your test code on Piazza for others to check, use and discuss.
We will provide a basic SpecChecker, but it will not perform any functional tests of your code. At this point in the course, you are expected to be able to read the specfications, ask questions when things require clarification, and write your own unit tests. The SpecChecker will verify the class names and packages, the public method names and return types, and the types of the parameters. If your class structure conforms to the spec, you should see a message similar to this in the console output: x out of x tests pass. This SpecChecker will also offer to create a zip file for you that will package up the two required classes. Remember that your instance variables should always be declared private, and if you want to add any additional helper methods that are not specified, they must be declared private as well. Style and documentation Roughly 15% of the points will be for documentation and code style. Here are some general requirements and guidelines: Use instance variables only for the permanent state of the object, use local variables for temporary calculations within methods. o You will lose points for having lots of unnecessary instance variables o All instance variables should be private. Accessor methods should not modify instance variables. Each class, method, constructor and instance variable, whether public or private, must have a meaningful and complete Javadoc comment. Class javadoc must include the @author tag, and method javadoc must include @param and @return tags as appropriate. o Try to state what each method does in your own words, but there is no rule against copying and pasting the descriptions from this document. o Run the javadoc tool and see what your documentation looks like! You do not have to turn in the generated html, but at least it provides some satisfaction :) All variable names must be meaningful (i.e., named for the value they store). Your code should not be producing console output. You may add println statements when debugging, but you need to remove them before submitting the code. Internal (//-style) comments are normally used inside of method bodies to explain how something works, while the Javadoc comments explain what a method does. (A good rule of thumb is: if you had to think for a few minutes to figure out how something works, you should probably include a comment explaining how it works.)
o Internal comments always precede the code they describe and are indented to the same level. Use a consistent style for indentation and formatting. o Note that you can set up Eclipse with the formatting style you prefer and then use Ctrl-Shift-F to format your code. To play with the formatting preferences, go to Window->Preferences->Java- >Code Style->Formatter and click the New button to create your own profile for formatting. If you have questions For questions, please see the Piazza Q & A pages and click on the folder assignment3. If you don t find your question answered, then create a new post with your question. Try to state the question or topic clearly in the title of your post, and attach the tag assignment3. But remember, do not post any source code for the classes that are to be turned in. It is fine to post source code for general Java examples that are not being turned in, and for this assignment you are welcome to post and discuss test code. (In the Piazza editor, use the button labeled tt to have Java code formatted the way you typed it.) If you have a question that absolutely cannot be asked without showing part of your source code, make the post private so that only the instructors and TAs can see it. Be sure you have stated a specific question; vague requests of the form read all my code and tell me what s wrong with it will generally be ignored. Of course, the instructors and TAs are always available to help you. See the Office Hours section of the syllabus to find a time that is convenient for you. We do our best to answer every question carefully, short of actually writing your code for you, but it would be unfair for the staff to fully review your assignment in detail before it is turned in. Any posts from the instructors on Piazza that are labeled Official Clarification are considered to be part of the spec, and you may lose points if you ignore them. Such posts will always be placed in the Announcements section of the course page in addition to the Q&A page. (We promise that no official clarifications will be posted within 24 hours of the due date.) Suggestions for getting started At this point we expect that you basically know how to study the documentation for a class, write test cases, and develop your code incrementally to meet the specification. The suggestions below are mainly intended to help you think about how to test your code. The most important
thing to remember is that you should not try to debug your code by running the GUI. Doing so is extremely slow and frustrating because of all the additional complexity of the GUI code itself. Write simple, focused test cases that you can easily understand and check. There are a number of examples below. 1. See the section "Importing the sample code" and make sure your project builds without compile errors. 2. Start by reading the code for the Cell and Flow classes that you will need to use. Notice that these classes both have a method tostring that allows their values to easily be printed using SOP. For example, you could try out the Flow class like this: public static void main(string[] args) { Cell e0 = new Cell(2, 3, 'R'); Cell e1 = new Cell(9, 10, 'R'); Flow f = new Flow(e0, e1); System.out.println(f); f.add(e1); System.out.println(f); System.out.println(f.getEndpoint(0)); } 3. Create instance variables for the game state, as described in the introduction. Implement the constructor that takes an array of Flows. This is easy. The "current" cell should initially be null. 4. Implement the simple accessors getwidth, getheight, and getallflows. Check that you're getting the right values (as passed into the constructor). It is easy to create a simple game and check: // create a simple game Flow[] flows = new Flow[3]; flows[0] = new Flow(new Cell(0, 0, 'G'), new Cell(1, 2, 'G')); flows[1] = new Flow(new Cell(0, 1, 'R'), new Cell(0, 3, 'R')); flows[2] = new Flow(new Cell(2, 0, 'B'), new Cell(1, 3, 'B')); FlowGame game = new FlowGame(flows, 4, 3); // check the initial game state System.out.println(game.getWidth()); System.out.println(game.getHeight()); System.out.println(game.getCurrent()); Flow[] temp = game.getallflows(); for (Flow f : temp) { System.out.println(f); }
(If that works, you should be able to run ui.gamemain to start up the GUI, and it should display your game as in Figure 2, but you won't be able to do anything else with it.) 5. Try implementing startflow. Initially, just implement the case where an endpoint is selected. Test it. For example, the game constructed in the sample code for (4) above, you should be able to try this, game.startflow(1, 3); System.out.println(game.getCurrent()); temp = game.getallflows(); for (Flow f : temp) { System.out.println(f); } You should see that the cell (1, 3, B) is now the current cell and it has been added to the correct flow: (1, 3, B) {(0, 0, G), (1, 2, G)} [] {(0, 1, R), (0, 3, R)} [] {(2, 0, B), (1, 3, B)} [(1, 3, B)] Try endflow too, it's simple. 6. The most interesting method is addcell(). As always, start by carefully reviewing its specification and write some simple test cases. For example, continuing with the example from above, you could try some calls like the following, checking the game state after each one. game.addcell(2, 2); // no change, cell is not adjacent to current game.addcell(0, 3); // no change, cell is occupied game.addcell(2, 3); // should add new cell to flow and update current System.out.println(game.getCurrent()); temp = game.getallflows(); for (Flow f : temp) { System.out.println(f); } To detect whether a cell is occupied, you can first implement and test the method isoccupied(). 7. You can actually get the whole FlowGame implemented and tested without the Util class, except for the second constructor that takes a string descriptor. For that, you'll want to first implement and test Util.createFlowsFromString. (After doing so, the constructor is easy.) 8. You can work on the Util class independently of the FlowGame. For createflowsfromstring, first do some examples by hand. There are many ways it could be implemented. As a warm up, make sure you can at least iterate over the characters, and print out the row, column, and letter for each letter you find. Then try making a list of Cell objects,
corresponding to the letters. Then create a list of Flow objects; to make the flows, you just have to look at your list and find each pair of cells with matching color, and create a Flow from them. If you have a list of Flows called mylist, you can easily convert it to an array with the somewhat strange toarray method, Flow[] myarray = mylist.toarray(new Flow[0]); 9. You can also work independently on the Util.readFile method. This is not too hard, once you have implemented createflowsfromstring. Note you'll need to identify blank lines, since that's how you recognize the end of a descriptor. This is easy; if theline is the string you've read from the file, just call theline.trim().isempty(). The catch to readfile is that there may or may not be a blank line at the end of the file, you'll have to deal with the case that the input loop ends while you're in the middle of processing a descriptor. There may also be blank lines at the beginning of the file. What to turn in Note: You will need to complete the "Academic Dishonesty policy questionnaire," found on the Homework page on Blackboard, before the submission link will be visible to you. Please submit, on Blackboard, the zip file that is created by the second SpecChecker. The file will be named SUBMIT_THIS_hw3.zip. and it will be located in the directory you selected when you ran the SpecChecker. It should contain one directory, hw3, which in turn contains the two files FlowGame.java and Util.java. Please LOOK at the zip file you upload and make sure it is the right one! Submit the zip file to Blackboard using the Assignment 3 submission link and verify that your submission was successful by checking your submission history page. If you are not sure how to do this, see the document "Assignment Submission HOWTO" which can be found in the Piazza pinned messages under Syllabus, office hours, useful links. We recommend that you submit the zip file as created by the specchecker. If necessary for some reason, you can create a zip file yourself. The zip file must contain the directory hw3, which in turn should contain the two required files. Make sure all files have the extension.java, NOT.class. You can accomplish this easily by zipping up the src directory of your project. The file must be a zip file, so be sure you are using the Windows or Mac zip utility, and not a third-party installation of WinRAR, 7-zip, or Winzip.