Com S 228 Spring 2011 Programming Assignment 1 Part 1 (75 points): Due at 11:59 pm, Friday, January 28 Part 2 (225 points): Due at 11:59 pm, Monday, February 7 This assignment is to be done on your own. If you need help, see me or one of the TAs. Please make sure you understand the Academic dishonesty section of the syllabus. Please start the assignment as soon as possible and get your questions answered early. Read through this specification completely before you start. This is a new project so there are likely to be problems. Check regularly for updates and clarifications. WebCT The WebCT discussion for Assignment 1 is a good place to post general questions. Please do not post or attach any source code for the assignment. Note that, although in future assignments it may be allowed, for this assignment you may not post any test code on WebCT. Be sure check the official clarification thread for corrections or updates to this document or to the distributed code. Introduction The purpose of this assignment is to give you a chance to review some of the basic skills you learned in Com S 227, to give you some practice working with interfaces and inheritance, and to ensure that you are able to create and run unit tests using the JUnit 4 framework. Much of the code (including all the UI and graphics) is already written, and your code will have to match the specifications in order to integrate correctly with the existing classes. The source code is in the cs228hw1.zip archive. See the section Getting Started for details. Summary of tasks There are two deliverables: Part 1: a complete JUnit 4 test for the LTetromino class, described below Part 2: a working implementation of the CS228Tetris game. The code to be supplied by you will include: 1. A class CS228Tetris extending AbstractBlockGame 2. Concrete implementations of the six Tetromino classes described below (which may include one or more abstract classes) 3. A class PolyominoFactory implementing IPolyominoFactory 4. A class BasicGenerator implementing IPolyominoGenerator
Note you will also need to modify the create() method of GameMain so that it constructs an instance of CS228Tetris instead of SampleGame. Overview In this project you will complete the implementation of a simplified Tetris-style or falling blocks type of video game. This particular game, which we ll call CS228Tetris, is a version of Tetris. If you are not familiar with such games, you can read about them on Wikipedia; see http://en.wikipedia.org/wiki/tetris The basic idea is as follows. The game is played on a grid with 24 rows and 12 columns. Each location in this grid can be represented as an (x, y) pair (its column and row). We typically represent these locations using the simple class java.awt.point. At any stage in the game, a grid position may be empty or may be occupied by an icon, which for this game is just a colored square, or block. In addition, a shape made up of a combination of blocks, called a polyomino, falls from the top of the grid. This is referred to as the current polyomino. In general the current polyomino can be shifted from side to side using the arrow keys, transformed using the up-arrow key, which may rotate or flip it, cycled by hitting the space bar, which will change the relative positions of the icons, without changing the locations of the cells (this is only noticeable for magic blocks, described later) In addition, the down-arrow can be used to increase the falling speed. When the currently falling polyomino can t fall any further, its blocks are added to the grid, and the game checks whether it has completed a row (or more generally, a collapsible group). All blocks in a collapsible group are removed from the grid and blocks above them are shifted down. A block may also be magic, which works like this: If a row is completed that contains three magic blocks, then gravity comes on for a moment, that is, all blocks with empty cells below them are allowed to fall independently. This normally results in some completed rows, which are then collapsed as usual. The user interface for the project, consisting of the classes in the edu.iastate.cs228.hw1.ui package, uses the Java Swing libraries. However, all the Swing code is already implemented so it is not strictly necessary for you to read and understand it. (Though you might find it interesting.) You should put all your new classes, other than your unit test, in the package edu.iastate.cs228.hw1.impl. Your unit test should be named LTetrominoTest and should be in the package edu.iastate.cs228hw1.test. The IPolyomino interface and the six concrete polyomino types See the javadoc for the IPolyomino interface.
The currently falling shape is represented by an object that implements the IPolyomino interface. Each polyomino has a state including The coordinates of its location (center of rotation) The actual icons or blocks that make up the shape The coordinates of the individual blocks (which can change depending on the transform() operation) Most importantly, there is a getcells() method that enables the caller to obtain the actual coordinates of the individual blocks. You will need to create six concrete classes implementing the IPolyomino interface, called the LTetromino, JTetromino, ITriomino, OTetromino, TTetromino, and SZTetromino. It is up to you to decide how to design these classes, but a portion of your grade will be based on how well you avoid duplicated code. Their initial configurations are summarized in the figure below. Every tetromino has a location, shown in the figure as a black dot. For those that rotate, this will also be the center of rotation. The captions describe the individual block coordinates, assuming an initial location at (0, 0). Remember that in this application the y-axis grows downward. The caption also specifies the action of the transform() operation. Figure 1- The six concrete Polyomino types Cell ordering The getcells() method always returns the cells of a polyomino in a fixed order. This ordering is just the reading order (left-to-right, top-to-bottom) when the polyomino is in its initial position, as shown in Figure 1. Note that if the polyomino is transformed, the ordering remains the same (there are more detailed rotation examples in the next section).
0 0 3 0 0 1 2 3 2 1 2 2 1 1 3 3 Figure 2 - cell ordering remains consistent after transform() Rotation examples The first picture below shows an LTetromino in its initial rotation at location (4, 1). The second, third, and fourth pictures show the results of successive invocations of transform(), which (for the LTetromino) results in a counterclockwise rotation about a fixed point. The list of coordinate pairs underneath each picture shows the locations that would be returned by getcells(), in the correct order. Figure 3- Rotations of an LTetromino The next example shows the four rotations of a JTetromino, starting in its initial rotation, again using the hypothetical location (4, 1). Center of rotation (4, 1) (3, 1), (3, 2), (4, 2), (5, 2) (4, 2), (5, 2), (5, 1), (5, 0) (5, 1), (5, 0), (4, 0), (3, 0) (4, 0), (3, 0), (3, 1), (3, 2) Figure 4 - Rotations of a JTetromino Colors, magic, and cycling See the javadoc for the Cell, IGameIcon, and Block classes.
A polyomino is made of Cell objects. A Cell encapsulates a location (x, y coordinates) and also an IGameIcon, which is primarily used by the UI as a hint for how to draw a given cell. The relevant methods are java.awt.color getcolorhint(); boolean ismagic(); IGameIcon is implemented by the simple class Block. A Block encapsulates a color and a magic state (which is just a boolean value). The way you associate a color with a Cell is by giving the Cell a Block containing that color for its IGameIcon. The cycle() operation of IPolyomino shifts the IGameIcon objects among the Cells of a polyomino. The cycle() method is invoked when the player presses the space bar. The order of this shifting matches the ordering of the cells returned by getcells(), as described above, that is, the IGameIcon at cell 0 is moved to cell 1, and so on, where the IGameIcon at the last cell is moved to cell 0. The following example shows an LTetromino with one magic icon, designated by the white circle, as cycle() is called 4 times. Figure 5- Invoking cycle() on an LTetromino with one block in the magic state Use the following constants from the java.awt.color class: Color.ORANGE Color.BLUE Color.CYAN Color.YELLOW Color.MAGENTA Color.GREEN Color.RED Equals Each polyomino class must override the equals() method of java.lang.object. Two polyominoes are equal if they have the same type and have equal cells. (The equals() method is already implemented for the Cell class.) Chances are you will be able to implement equals() just once in an abstract superclass. The IGame interface and AbstractBlockGame class See the javadoc for the IGame interface. The class AbstractBlockGame is a partial implementation of the IGame interface. The GUI interacts with the game logic only through the interface IGame and does not depend directly on the
AbstractBlockGame class or its subclasses. AbstractBlockGame is a general framework for any number of Tetris-style games. It is specialized by implementing two abstract methods. List<Point> determinecellstocollapse() Examines the grid and returns a list of locations to be collapsed. int determinescore() Returns the current score. The key method of IGame is step(), which is called periodically by the GUI to transition the state of the game. The step() method is fully implemented, and it is not necessary for you to read it in detail unless you are interested. You will just need a basic understanding of how it interacts with the determinecellstocollapse() method that you will implement, described in the next section. You should not modify anything in IGame or AbstractBlockGame. The CS228Tetris class You will create a subclass of AbstractBlockGame, called CS228Tetris, that implements the game described in the introduction. The methods determinecellstocollapse and determinescore must be declared public (this requirement is to make it easier for us to test your code). The determinescore() method should just return the total number of rows that have been collapsed in the game so far, so this is pretty easy. In CS228Tetris, the main task of determinecellstocollapse() is to identify the locations of cells in all completed rows and return an ArrayList of Point objects containing those locations. The method returns an empty list if there are no completed rows. (Note the return type is List<Point>, since List is the interface implemented by ArrayList.) This part is also pretty easy. However, you ll also have to deal with magic blocks. The way that determinecellstocollapse() is invoked from AbstractBlockGame is the following. Whenever the current polyomino cannot fall any further, the step() method calls determinecellstocollapse(). If the returned list is nonempty, then the list is stored in the state variable cellstocollapse, the game goes into the COLLAPSING state (which allows the GUI to perform some animation of the cells to be collapsed). On the next call to step(), the method collapsecells of AbstractBlockGame is invoked to actually remove the cells from the grid and shift down the blocks above them. In certain games, collapsing some cells may create additional collapsible groups, possibly starting a chain reaction, so the logic of the COLLAPSING state is basically the following: while (game state is COLLAPSING ) { collapsecells(cellstocollapse); cellstocollapse = determinecellstocollapse(); if (cellstocollapse.size() == 0) { generate a new current polyomino change game state to NEW_POLYOMINO }
} Here is how it works in this game: if a completed row contains three or more magic blocks, then your game needs to go into gravity mode. What this means is that on the next call to determinecellstocollapse(), you should return a list of all the locations of empty cells that have one or more nonempty cells above them. (When the game then collapses those cells, it will have the effect of allowing the blocks above to independently fall to the bottom.) Then go back into normal mode, so that on the next call to determinecellstocollapse(), you will again just return the locations of cells in completed rows, if any. Remember that you do not have to implement the algorithm for collapsing cells, which is already implemented in AbstractBlockGame (the collapsecells() method). The PolyominoFactory class See the javadoc for the IPolyominoFactory interface. The purpose of this class is to make it easier for us to test your code. (You may wish to use the factory in your implementation of BasicGenerator, below, but that is optional.) Since you are defining the polyomino classes, we have no way to know what constructor or constructors you will define. Using a factory gives us a consistent way to create instances of your polyomino classes without knowing what the constructors are. The BasicGenerator class See the javadoc for the IPolyominoGenerator interface. You ll need to implement a BasicGenerator class implementing IPolyominoGenerator so that it returns one of the 6 concrete polyomino classes, chosen uniformly at random. In addition, each polyomino should include a magic block with probability 1/10. You must use the following initial positions for the polyominoes: LTetromino (7, -1) JTetromino (6, -1) ITriomino (6, -2) OTetromino (5, -1) TTetromino (6, 1) SZTetromino (5, -2) When a polyomino includes a magic block, it should be located in the first cell (according to the ordering defined previously in the section entitled The IPolyomino interface and the six concrete polyomino types ).
Getting started The user interface, and other source code, in the cs228hw1.zip archive is an Eclipse project that you can import and build. Run the main class edu.iastate.cs228.hw1.ui.gamemain. This will start up a SampleGame and you should see a simple animation which shows a Sampleomino (a simple two-cell polyomino) falling from top to bottom. You can put it into fast drop mode by pressing the down arrow key. A good place to start is to try to implement the missing methods of that will enable you to move the Sampleomino left and right. Then you could implement the determineblockstocollapse() method of SampleGame so that it finds completed rows. This would give you a rudimentary form of Tetris. Part 1 requires you to turn only your JUnit 4 test for the LTetromino. However, it is probably going to be easier to develop the test code if you have begun to implement the LTetromino class at the same time. Grading Your grade for Part 1 will mainly be determined by running your JUnit test on some correct and incorrect versions of LTetromino. The correct versions should pass your tests, and the incorrect versions should fail appropriately. A significant portion of your grade for Part 2 will be based on running our unit tests on your polyomino classes. A portion of your grade for Part 2 will be determined by how well you make use of inheritance to minimize code duplication in your polyomino classes. You will most likely need to create a polyomino superclass containing common code. Documentation and style Roughly 15% of the points will be for documentation and style. There is a brief set of guidelines to follow in the Course Specific section of the Web Links on our WebCT page (also linked in the syllabus). What to turn in For Part 1: Turn in a zip file containing your unit test LTetrominoTest ONLY, in the correct directory structure (root directory should be edu). For Part 2: Turn in a zip file containing all source code, including the distributed code. For detailed instructions on how to create a zip file and submit it via WebCT, see the Course Specific section of the Web Links (also linked in the syllabus). Late Penalties Assignments may be submitted up to 24 hours after the deadline with a 25% penalty (not counting
weekends/holidays). No credit will be given for assignments submitted after that time.