CompSci 6, Fall 2006, Dots Assignment

Snarfing Code

Using Eclipse, snarf the Dots assignment.

Problem: Dots

For this assignment you'll write some of the classes used to play a game of dots. Other classes are written for you and you'll use them in implementing the classes Box and DotsModel.

The game of dots allows each of two (or more) players to draw an edge between two dots. The players alternate drawing edges. When four edges form a box, the player who just completed the box gets to "claim" it with his/her initial and gets to make another edge. When all edges are taken, and all boxes outlined, the player with the most boxes wins.

Here's part of a game as played by a complete version of the program you're writing. This version uses players named Owen and Susan on a 2 x 2 board.

(user entered input in italics).


    0      1      2      
  0 +......+......+
    .      .      .
    .      .      .
    .      .      .
  1 +......+......+
    .      .      .
    .      .      .
    .      .      .
  2 +......+......+
    0      1      2      
Susan enter point 1> 0 0 
Susan enter point 2> 1 0 

    0      1      2      
  0 +------+......+
    .      .      .
    .      .      .
    .      .      .
  1 +......+......+
    .      .      .
    .      .      .
    .      .      .
  2 +......+......+
    0      1      2      
Owen enter point 1> 1 0 
Owen enter point 2> 1 1 

    0      1      2      
  0 +------+......+
    .      |      .
    .      |      .
    .      |      .
  1 +......+......+
    .      .      .
    .      .      .
    .      .      .
  2 +......+......+
    0      1      2

Note that the origin here is in the upper-left corner, that x-coordinates increase to the left and y-coordinates increase downward. The first coordinate of a point entered by the user is the x-coordinate as the example run above shows.

If the user picks an edge that's not on the board, or already taken, the program prints an error message.

Owen enter point 1> 0 1
Owen enter point 2> 2 1
that edge is illegal, try again
    0      1      2      
  0 +------+......+
    .      |      .
    .      |      .
    .      |      .
  1 +......+......+
    .      .      .
    .      .      .
    .      .      .
  2 +......+......+
    0      1      2      
Owen enter point 1> 0 0 
Owen enter point 2> 1 0 
that edge is used, try again
    0      1      2      
  0 +------+......+
    .      |      .
    .      |      .
    .      |      .
  1 +......+......+
    .      .      .
    .      .      .
    .      .      .
  2 +......+......+
    0      1      2      
Owen enter point 1> 0 1 
Owen enter point 2> 1 1 
    0      1      2      
  0 +------+......+
    .      |      .
    .      |      .
    .      |      .
  1 +------+......+
    .      .      .
    .      .      .
    .      .      .
  2 +......+......+
    0      1      2

If a player completes a box, she gets another turn:

    0      1      2 
  0 +------+......+
    .      |      .
    .      |      .
    .      |      .
  1 +------+......+
    .      .      .
    .      .      .
    .      .      .
  2 +......+......+
    0      1      2      
Owen enter point 1> 0 0 
Owen enter point 2> 0 1 

    0      1      2      
  0 +------+......+
    |      |      .
    |   O  |      .
    |      |      .
  1 +------+......+
    .      .      .
    .      .      .
    .      .      .
  2 +......+......+
    0      1      2
Owen enter point 1>

When all edges/boxes are taken the game is over and the player with the most boxes wins.

Classes and The Design of Dots

You'll need to implement most of the classes Box and DotsModel. You should not need to modify any other classes. You will need to add some code to DoDots to tell which player has won the game. You should not modify classes other than those you are asked to modify.

Complete Classes You Start With---Do Not Modify These

Point and Edge

You will be using the Point class as described in the Java API. You've used it before. You are given also given the complete file for the class Edge. Documentation Edge and other classes can be found imbedded in the code. You should be sure to read this documentation to understand the program structure. These classes are mostly support classes for the class Box.

The class Point represents an ordered pair (x,y). Points can be compared for equality using equals, printed (implicitly using toString), constructed, and translated. Translation means changing the x- and y-coordinate by some amount. See the Java API for more details.
The class Edge is defined by two points. In the dots game these points will be adjacent either horizontally or vertically. Edges can be compared for equality and the edge (p,q) is considered equal to the edge (q,p) where p and q are points. Edges can be printed too for debugging because a suitable toString has been provided.

Player

The class Player in its current version simply stores a player's name.

DotsViewer

The class DotsViewer shows a model---that is the current state of the boxes/game. This is a text view of the model, you can study the code to see how the classes Box and Edge are used in printing the board the players see. See DotsViewer for details.

Implementing the class Box

The class Box is a collection of edges; the collection represents a box on a dots board. The Box methods are described in the comments of the code. You must implement most of the class Box.

Some Box Details (read more than once, after reading the rest of this section)

In the Box class, the private arrays myEdges and myUsed are parallel arrays, that is the edge defined with index 0 in myEdges has its use status recorded with index 0 in myUsed. In general, the edge in myEdges[k] has used-status stored in myUsed[k]. Note that in the part of the method init implemented for you, a value is assigned to myEdges[TOP]. The value in myUsed[TOP] corresponds to this edge, and it's initialized to false (all edges are initially not used) in the Box constructor. Each time that addEdge is called and a new edge is successfully added your code will need to update the array myUsed so that the entry with the index corresponding to the added edge is set to true since the edge will now be used. (Read that again after looking at the code).

You need to implement several of the of the Box methods. To help you determine if you've implemented the functions correctly you're given a test program in TestBox.

Your goal is to run this program, have it do all the tests, and have it print nothing. When you copy it and run it initially, it will print error messages indicating that some tests have failed. You should implement the corresponding Box methods, run the tests, then when the tests pass (there's no output), you'll run the other test functions from TestBox

Summary of running TestBox

Run TestBox.

Initially the program runs the test function testInit() which tests methods isFree and the init function (called from the constructor). You'll need to implement these functions (and perhaps others) to pass the tests. After your code passes tests, when there's no output from running TestBox, you'll uncomment one of the commented-out test function calls from main, e.g., testEdges.

Looking at the test code, you'll implement more Box methods until the tests pass. Then you'll uncomment the last commented-out function call from main, pass these tests, and be confident your Box class is correct. There are three test-functions in TestBox

run TestBox, make it pass the tests in testInit
uncomment the call to testEdges and pass those tests
uncomment the call to testAdding and pass those tests

Do not proceed to the next step until your code passes the tests.

Implementing the class DotsModel

The class DotsModel stores the state of a dots game. This means it stores how many boxes there are and other game information. The boxes store edge and other information so that most of the DotsModel code consists of finding the right Box and interacting with that Box.

In the version you're writing, the Boxes are stored in an array of Boxes. For example, on a 2x3 dots board a DotsModel object will need to store 6 Boxes. On a 4x5 dots board 20 Boxes will be stored in the private array myBoxes. Your implementation can store the boxes in any order, but you must store all the boxes for a game. Note that client programs like DotsViewer request all the boxes from a model one at a time. The order in which your code returns the boxes doesn't matter, so you can store boxes in any order. However, the function initialize constructs the boxes.

Please read the description of the model class before testing.

DotsModel methods

Since the order in which boxes are stored in the model doesn't matter, nearly all the methods you implement will search all boxes. This means, for example, that to determine whether a specific edge is used in the model, e.g., in a call to edgeUsed, your code will examine every box in the model and call Box methods to determine if the edge is used in this case, or other Box methods in other DotsModel code.

Anatomy of addEdge

The header for addEdge is shown below. Pseudo-code for the implementation is given to help you understand the relationship between the DotsModel class and the vector of Boxes that store most of the game state. Note that the pseudocode looks at every box in the model. Futhermore, even when a box is found to which the edge can be added boxes are still examined. This is necessary because some boxes can share an edge.

/** assume isOk(e), i.e., e is in model, not used * @return e added to model, returns true if adding e completes * at least one box to which it's added and returns false otherwise * note: returns false if e not added to model */ boolean addEdge(Edge e, Player p) { initialize boxFilled to false; foreach of the k Boxes in myBoxes { if possible, add e to the k-th box if the k-th box is completed by adding e then occupy the k-th box with player's name set boxFilled to true since at least one box filled endif endif } return boxFilled; }

The TestModel program

There is a program TestModel similar to TestBox for testing the dots model class. You'll implement methods in the class DotsModel using a process similar to the testing done in implementing the Box class. After your DotsModel code passes the tests called in testOneOne() of TestModel by printing nothing when that program is run, you should then uncomment the call to testOneTwo and ensure your DotsModel code passes its tests.

After testing

After testing the DotsModel class you can run the game. If you run the DoDots program you may find that something doesn't work as intended despite passing the tests in TestModel. The testing is designed to be complete, but it's possible you pass the tests and the game doesn't work as it should. In that case you'll need to test by playing games.

Final changes to DotsModel

The current Model class doesn't keep track of how many boxes are occupied by each player. For full credit on this assignment, you should design a solution so that the DotsModel class keeps track of how many boxes each player using the model has "captured". You can add any state you want to the private section of the DotsModel class, and you can add new public/private mehtods to the class.

Alternatively, you can model the Player class to track how many boxes a player has and use this information. In any case, your game-playing code must determine when a game is over and who wins the game.

Submit

When your program compiles and produces the correct output, create a file named README (please use all capital letters in naming the file). In the file include your name, section number, the date, and an estimate of how long you worked on the assignment . You must also include a list of names of all those people with whom you consulted on the assignment. See the course web page for the meaning of consult.

Submit your project as Dots, using the Ambient menu within Eclipse. Always be sure to submit all java files, even if you did not modify them. You must also submit a README file too.