CS21 Lab 7: Mastermind

Design due March 21; Full game due March 28, 2015

Please read through the *entire* lab before starting.

Run update21 to create your cs21/labs/07 directory and create your programs for lab 7 in this directory.


Over the next two weeks you will write a program that plays the game Mastermind. This week you will focus on using top-down design to create the overall structure of the program. Once your proposed structure has been reviewed by your professor, you will use bottom-up implementation and unit testing to incrementally implement and test the full program (due March 28).

The wikipedia page about Mastermind describes the game and also some ineteresting results obtained by computer scientists who have studied the game. If you take more computer science courses at Swarthmore, you will learn about NP-complete problems in our Algorithms and Theory courses. Also, you can try playing the game on-line (but our version won't use graphics!).


Mastermind is a code-breaking game for two players. For our text-based version, the computer will be the code maker and the user will be the code guesser or breaker.

At the start of the game the computer will create a 4-letter code, where each letter is one of 6 possible letters (abcdef). Possible codes are ABCD, AAAA, BCBF, and so on. The user then has 12 chances to guess the code. After each guess, the computer tells the user how many exact and partial matches they achieved.

To make things more concrete let's consider some examples. Below is an example of just part of the game -- a code (usually not shown!) and multiple guesses, to show exact and partial matches.

code = "DDEC"

 1: abcd
                        0 exact matches
                        2 partial matches
 2: deff
                        1 exact match
                        1 partial match
 3: dddd
                        2 exact matches
                        0 partial matches
 4: eedd
                        0 exact matches
                        3 partial matches

Below are more details about specific requirements for the full mastermind program. Next we list the Top-Down-Design (TDD) requirements. Remember, the design is due this week, the full program next week.

Top-Down Design

The focus of this assignment is for you to practice using top-down design to construct your solution incrementally. This assignment spans two weeks. In the first week, you are required to design your solution and implement minimalistic function stubs for your design. In the second week, you will finish implementing and testing the full game.

Note: Once you have your top-level design done you should run handin21 and send me an email that you have completed your top-level design. I will look at your design and email you with feedback on your design within 24-48 hours. Please wait to hear back from me before continuing with the implementation of the full game (I may ask you to re-think your design). The earlier you handin your design, the earlier you can continue working on your full program.

For the design of the program in the first week, you should have:

Here is a simple example of a top-down design.

Mastermind Examples

Here are a few examples of a working program. Please look through the examples and note the details of how this program should work (e.g., how both upper and lowercase input is accepted, or what the special inputs ("quit" and "dbug") do).

Example 1
Example 2

Requirements for the full mastermind game

The requirements for a working mastermind game are:

  1. The program prints out a welcome message and the game rules for the player
  2. The computer generates a secret code
  3. The user enters up to 12 guesses
  4. After each guess, the program prints out the number of exact and partial matches
  5. The game ends if the user enters the correct code
  6. The program prints out a win or lose message to the player. If the player loses, it should print out the secret code.
  7. Your program needs to ensure that only valid input values are entered by the user (see the examples above)
  8. See the above examples for additional requirements...
Helpful tips

Once you are satisfied with your programs, hand them in by typing handin21 at the unix prompt. Don't forget to send us an email when you handin your design!