Goals

You will be practicing the following concepts from prior labs:

• while-loops
• conditionals
• the graphics package
• writing functions
• writing docstrings
• handling exceptions

---

Summary

In this project, you will make a simple matching game using the graphics package. The idea is that users will click on cards one at a time, to flip them over to find pairs. The below video shows the final game and a demonstration of gameplay.

Due Dates

• Checkpoint A: Due as a demo in workshop, lab, or tutoring hours before Thursday Mar. 28 at 7PM
• Checkpoint B: Due as a demo in workshop, lab, or tutoring hours before Monday Apr. 8 at 5PM
• Final code: Due via Moodle on Monday, Apr. 15 at 11:55 PM

---

Getting Started

Download the following files into your PyCharm directory for Project 02:

• yourlastnameP2.py, a blank template for Project 2
• graphics.py
• match_graphics.py, a support library for this project.
• icons.zip (sealife set) or icons.zip (adventuring set) or build your own set (see Extra Credit).

Do not modify match_graphics.py.

The file icons.zip should be unzipped to create the directory icons/ which holds a series of .gif files. Do not rename these graphics or their parent directory, since the file names are listed in match_graphics.py. The directory icons/ needs to be in the same directory as graphics.py, as match_graphics.py and as your code.

---

Checkpoint A

For Checkpoint A, you will need to demonstrate a program that draws the game board with all the cards shown. You need to be able to display the following window to complete the checkpoint:

Specifically:

• Complete the shuffle_cards() and show_card() functions (read their docstrings for guidance).
• The board is comprised of 25 rectangles with a 'Yellow' border of width 5-pixels. A card image is centered in each rectangle.
• The cards are randomly shuffled and placed each time. There are 24 pairs of cards and one extra card.
• Each time you start your program, the extra card should be randomly selected and the placement of the cards within the grid should be random.
• Use the constants defined in match_graphics.py for the window dimensions, etc. You can see how these constants relate to the board using the image below:
  
• Demo. Demo Checkpoint A.

Hints:

• Review all the code in match_graphics.py.
  This holds important constants, data structures and functions that you are expected to use in your program. For example, the names of the card images (in the icons/ directory) are written in a list, called images.
• The 'hidden cards' in our game are rectangles filled 'LightGreen' with yellow, 5-pixel borders. If you have a Rectangle() called r1, you can give it a border using r1.setOutline('Yellow'). To make its border 5 pixels wide, use r1.setWidth(5). See our past labs if you need help recalling how to fill a shape with a color using the graphics library.
• Complete the shuffle_cards() function.
  The goal of the shuffle_cards() function is to generate a two-dimensional cards list, where cards[i][j] holds the name of the card that should appear at position (i,j) in the board grid. The function shuffle() from the library random can be used to randomly permute the list, modifying the list in place. Thus, shuffle(images) will shuffle all the images.
• To display an image, use the Image() object from graphics.py. The documentation is here: http://mcsp.wartburg.edu/zelle/python/graphics/graphics/node13.html.
  Here is some sample code that displays "sample.gif" centered at the point (400, 400) in a window called win:

  card = Image(Point(400, 400), "sample.gif")
  card.draw(win)

---

Checkpoint B

Your Checkpoint B code needs demonstate the following:

• The game should start with all cards hidden, like this picture
• The game should cycle through pairs of rounds, where the user is either making a 'first pick' (round n) or a 'second pick' (round n+1).
  • On a 'first pick,' the card they click is shown.
  • On a 'second pick,' the second card they click is also shown.
  • After the 'second pick' is shown, pause for 1 second and then decide if the 'first pick' and the 'second pick' are a match.
  • If they are a match, leave both showing. If they are not a match, hide both.
• If the 'second pick' is the same exact card as was selected in the 'first pick,' then the game should ignore the most recent 'second pick' and let the user make a different 'second pick' instead.
• If a 'pick' is off the game board, then the game should ignore the click and let the user make a different 'pick.'
• Demo. Demo Checkpoint B.

Hints:

• To accomplish the above tasks, you need to implement the hide_card(), get_col() and get_row() functions.
• To pause the game for 1 second, call the function game_delay(1).
• Implementing the above, you may find the continue or break control-flow keywords useful. These are demonstrated in this PythonTutor code.

---

Final Code

In your final code, you will extend your Checkpoint B code. At this point, the game will mark matches, remember prior matches and detect when we have enough matches to declare victory. It should look just like the opening video in behavior.

• When two cards are 'matched,' then draw a red 'X' across each card. Implement the mark_card() function.
• When a 'pick' is made that is a card that is already shown because its part of a match, ignore this click and let the user 'pick' again.
• When all pairs of cards are matched, detect that the game has been won and call the you_won() function.
• If the user closes the graphical window at any point, your program should simply exit cleanly. In other words, encorporate exception-handling logic to deal with the GraphicsError exception.

Hints:

• For the final code, you will need to implement the mark_card() function.
• To remember that the card at row i and column j has been matched with some other card successfully, consider adding the pair (i,j) into a list to track this data. To add something to the end of the list, use its append() member function:

  matches = []
  ...
  pair = (i,j)
  matches.append(pair)

• To see if (i,j) is in a list, you can use the following conditional logic, demonstrated here in some PythonTutor code too:

  if (i,j) in matches:
      print("Hey, (i,j) is in the list 'matches'")
  

There is no demo for your final code. See the end of this specification for submission instructions.

---

Extra Credit

You can get up to 10 points total for extra credit. Extra credit is to create a second verson of the game that is extended or enhanced in some creative way. There are lots of possibilities. For example, you may select alternative game icons from http://game-icons.net (I converted these to 125x125 pixel GIFs to make the two icon sets provided above). You may also use different color schemes to create your own themed game, change rules, add scoring.

To qualify for extra credit you must (1) submit a version of your game without any extra credit enhancements, following the standard submission instructions below and (2) submit your customized game to the "Project 2 extra credit" assignment on Moodle as a single ZIP file containing all the files for your enhanced game. The enhancements must be described in the docstring of the extra credit version.

---

Grading Rubric

Checkpoints [20%]

Checkpoint demos are each worth 10 points; each is all or nothing.

Correctness [55%]

The most important part of your grade is the correctness of your final program. Your program will be tested numerous times, using different inputs, to be sure that it meets the specification. Attention to detail will pay off on this assignment. For details, see the rubric below.

Programming Design and Style [25%]

In addition to being correct, your program should be easy to understand and well documented. For details, see the rubric below.

Detailed Rubric

Correctness: functional features (55 points)

The following must be true to receive any points for the correctness aspects of the game:

• The game board dimensions must match the figures and descriptions provided in the assignment description (5x5 grid, margins as defined, color at card borders both when hidden and shown, etc).
• The board is comprised of the correct number of pieces (12 pairs of images plus an extra image), whose positions and identities are randomized each game.

Game Behavior (55 points)

5 pts.	On game start, the board is drawn with all cards hidden.
5 pts.	When the hidden card at coordinate (i,j) is clicked, the card at coordinate (i,j) is shown.
5 pts	The 'first pick' stays shown until a 'second pick' is made, at which point both are visible for a brief period of time (after this, what happens depends on if they match).
5 pts	When the 'first pick' and 'second pick' match, they stay visible and get a red 'X' drawn over their faces.
5 pts	When the 'first pick' and 'second pick' are not a match, they are hidden again.
5 pts	A red 'X' is never drawn over unmatched cards.
5 pts	Matched cards stay visible and stay marked with an 'X' for the duration of the game.
5 pts	When making a 'first pick', the following actions are ignored: clicking in the margins of the board, clicking cards that are matched.
5 pts	When making a 'second pick', the following actions are ignored: clicking in the margins of the board, clicking cards that are matched, clicking any unhidden cards (like the 'first pick').
5 pts	The winning condition gets detected when all pairs have been matched, and the you_won() function is called in this scenario.
5 pts	Program exits without any error messages if the graphics window is closed.

Programming Design and Style (25 points)

Filename (1 point)

1 pt.

Your program should obey the naming convention indicated in the assignment.

Docstring (3 points)

There is a docstring at the top of the submitted file with your name (first and last), the course (CS 115) and assignment (Project 2), and a brief description of the program.

1 pt.	Your name (first and last)
0.5 pt.	The course (CS 115)
0.5 pt.	The assignment (Project 2)
1 pt.	A brief description of what the program does

Function behavior (4 points)

Each function matches its description and each function implementation is not too long (no more than 20 lines of code).

-1 pt.	Not true of one function.
-2 pts.	Not true of half or fewer of the functions.
-4 pts.	Not true of more than half the functions.

Function documentation (3 points)

You have completed the docstrings of all functions. Each function includes a docstring explaining the job it does, its input parameters, its return value, and any assumptions it makes about its inputs. See match_graphics.py for examples of how to effectively document functions, their parameters and return values.

-1 pt.	Some function doctring is significantly incomplete.
-2 pts.	Some functions do not have completed doctrings.
-4 pts.	Most functions do not have completed docstrings.

Other documentation (3 points)

Not counting the docstrings for your program and functions, your program should contain at least three comments explaining aspects of your code that are potentially tricky for a person reading it to understand. You should assume that the person understands what Python syntax means but may not understand why you are doing what you are doing.

3 pts.

You have at least 3 useful comments (1 points each)

Variables (4 points)

Important variables have descriptive names that indicate what they are used for.

2 pts.	Variable declarations are not accompanied by comments.
2 pts.	Variables do not have names that suggest for what they are used.

Algorithm (2 points)

1 pts.	Your algorithm is straightforward and easy to follow.
1 pts.	Your algorithm is reasonably efficient, with no wasted computation or unused variables.

Structure (5 points)

You will lose 5 points for having any statements outside of a function definition. There are only three exceptions to this rule:

• Import statements
• Definition of constants (variables whose values are known before the program runs and never modified)
• The call to main

Catchall

For students using language features that were not covered in class, up to 5 points may be taken off if the principles of programming style are not adhered to when using these features. If you have any questions about what this means, then ask.

---

Submission

You should submit your final code on Moodle by the deadline. I strongly encourage you to take precautions to make and manage backups while you work on your project, in case something goes wrong either while working or with your submission to Moodle.

Name the file you submit to Moodle yourlastnameP2.py, substituting your actual last name (in lowercase) for yourlastname.

Late Policies

Project late policies are outlined in the course policies page.

Collaboration Policy

Programming projects must be your own work, and academic misconduct is taken very seriously. You may discuss ideas and approaches with other students and the course staff, but you should work out all details and write up all solutions on your own. The following actions will be penalized as academic dishonesty:

• Copying part or all of another student's assignment
• Copying old or published solutions
• Looking at another student's code or discussing it in great detail. You will be penalized if your program matches another student's program too closely.
• Showing your code or describing your code in great detail to anyone other than the course staff or tutor.

Project collaboration policies are described in the course policies page.