2009 April 3 / jjddaavviiss@@ccaarrlleettoonn..eedduu

Tic Tac Toe

Carleton College CS 201, Spring 2009, Prof. Joshua R. Davis

The goal of this assignment is to practice writing Python code — in particular, writing classes and subclasses and using a graphics library. By the end, you will have a functioning two-player Tic Tac Toe game. If you dislike Tic Tac Toe, then you are welcome to implement another, comparable board game, such as Connect Four or Reversi. Clear your idea with me or Eric before starting on it, though.

You are expected to complete this assignment with one partner. It is due Monday at 5:00 PM.

0. Get Ready

bopa.py is the Bopa 2D graphics library. Save this file to your computer, in the same directory where you'll be working.
bopademo.py is a simple demo program for Bopa, just to give you an example. Save it to your computer.
Bopa Manual explains things more explicitly. You'll want to keep it handy.

Open a Terminal window and navigate to your working folder (where you stored the files above). You might find these Unix commands helpful:

pwd tells you your current directory; it's like asking "Where am I?". By default you start in your home directory.
ls tells you what's in your current directory; it's like asking "What's here?".
cd SUBDIRECTORY (where SUBDIRECTORY is one of the directories in your current directory) changes your current directory to that subdirectory.
cd .. goes "up" — that is, changes your current directory to the one that contains it.
cd (with nothing else) changes your current directory to your home directory. Use this if you get lost.
cat FILE (where FILE is one of the files in your current directory) shows you the contents of that file. It doesn't let you edit the file; for that, use TextWrangler.
python FILE (where FILE is a Python program file in your current directory) executes the program in that file.

Open the TextWrangler text editor, too.

1. Try A Little Bopa

Read the "Getting Started" section of the Bopa manual. Definitely try out the starter code for yourself. Also skim the next two sections of the manual, to get an idea of which shapes are available and what you can do with them.

By default, you can drag any Bopa shape around with your mouse, as if it were a physical object. How does this work? The Bopa window waits for the user to use the mouse (or keyboard). When the user drags the mouse pointer on a shape, the window tells the shape to translate() in whatever direction the mouse moved.

This is the basic idea of your board game program: Make a board and some pieces, and let the users drag the pieces around.

2. Design Your Window And Board

On paper, sketch what the window for your game will look like. Somewhere in that window is a board of some kind. Make your sketch as detailed as possible; for instance, figure out how many pixels long each part of your board is. You'll need to know this when you write code to draw the board.

In a new file called game.py, write a new class called Board. It should be a subclass of Overlay or of one of Overlay's subclasses. Your code for Board should accomplish two things:

The board should look like the game board that you designed above. You make this happen by choosing a shape for Board itself, and by attaching child shapes. For example, if you were making a game with a green, circular board with yellow triangles on it, then you might make Board a subclass of Circle. In its __init__() method you set its color to green and attach a bunch of yellow triangular shapes as children. Read "Child Shapes" in the Bopa manual about attaching children.
The user should not be able to drag the board around with the mouse. You need to make the board immobile. You can accomplish this by overriding translate() to do nothing.

After you write your board code, test it out. How? At the bottom of game.py, write a little code that makes a window, creates a Board, and starts the window running. Then run game.py to make sure everything works so far. Checking your program periodically as you write it, rather than once after you've written everything, can save you a lot of time! (And I don't use exclamation points often.)

Now is a good time to document your Board class. Make sure there are comments for any large or non-obvious chunks of code. Also make sure that your name(s) are typed in comments at the top of the file, along with the date.

3. Design Your Pieces

Now that you have a board, you need some pieces. For Tic Tac Toe these are Xs and Os. Draw them on paper, in as much detail as possible, including the length of each part of each piece, in pixels.

Write classes for your pieces. For my version of Tic Tac Toe I used an XPiece class and an OPiece class. In each, all I really did was override __init__() to set up my desired color and size and attach child shapes.

Test your piece class(es).

Write documentation for your piece class(es).

4. Write The Game Logic

Your program is required to post a message of some kind to the Bopa window when the game is finished. This means that you need to keep track of the state of the game somehow, test the state of the game after each move, and display a message if one player or the other has won (or if the game has ended in a draw). Depending on how you decide to do this, you may have to go back and alter your board and piece classes.

To help you out, let's talk about the logic of Tic Tac Toe. There is a 3 x 3 board. When a user moves a piece, your program must figure out which square of the board the piece was dropped on, record the fact that the piece now occupies that square, and check the board to see whether that player now occupies an entire row, column, or diagonal. If so, she wins; if not, then either all the squares are occupied (draw) or some are still unoccupied (play on).

Let's expand on that first step — figuring out which square the piece was dropped on. When you think about it, you don't really care how the user drags the piece around, or how long it takes; you just want to know the final resting place of the piece. This is exactly what Window's setEndOverlayDragHandler() method gives you. It's covered in the "User Interface" section of the Bopa manual. Here's a little example of how you might use it. Define this handler function somewhere in your program.

def myendhandler(xyStarting, xyPrevious, xyFinal, names):
    print 'piece dropped at', xyFinal[0], xyFinal[1]

Then, in the main body of your program (between creating the window and running the window's loop), attach the handler function to the window like this:

mywindow.setEndOverlayDragHandler(myhandler)

Now, whenever the user drags a piece, that piece's final resting place will be printed out. Of course, you don't want your Tic Tac Toe program to print out the final resting place; you want it to figure out the new state of the game, and whether the game is finished or not. That's your job.

5. Polish

This assignment is a little open-ended. You can design your program however you like, as long as it is a recognizable version of the game you were approved to make, that behaves correctly and displays a useful message in the Bopa window when the game is finished.

However, as you can see from the grading criteria in the next section, one quarter of the points are reserved for creativity and polish. How might you earn these points?

Handle various kinds of user error. What happens when the user drags a piece out of the window? Is it lost? What happens when a user moves out of turn? What happens when a user tries to move a piece that's already on the board? It's desirable for your program to enforce some basic rules of the game.
In my version of Tic Tac Toe, when a user drops a piece onto a square I center the piece on that square. And I don't center it suddenly; I gently slide it into position using an Animation. (See the Bopa manual.)
Make a beautiful board or pieces.
Think of your own ideas. Be creative.

In a comment near the top of the file, explain what kind of creativity or polishing you've performed that deserves points. If you don't make this explanation/declaration, then you will not be considered for these points.

6. Hand In Your Work

Your file game.py will be graded using these criteria:

Does the basic game work, well enough that I can tell that I'm playing Tic Tac Toe, or whatever your approved game was? (3 points)
Does your program announce the end of the game in the Bopa window correctly, in all cases? (3 points)
Is the code clean and appropriately commented? Remember that your name(s) and the date must be at the top of the file. (3 points)
Creativity and polish. Remember that you must explain your creativity/polish near the top of the file, to be considered for these points. (3 points)

Each pair of students should submit one copy of game.py with both of their names on it. There are two ways to submit it.

This first method works only on our lab computers. In the terminal, make sure that you are in the directory where the file is. Then type
hsp game.py cs201-00-s09
This command launches the CS department's homework submission program. It will ask for your usual Carleton password. If you have problems, contact Mike Tie in CMC 305.
Alternatively, connect to the COURSES file server, navigate to our course and your folder within it, and place your file into your hand-in folder.