## CS21 Lab 8: The Game of Melty, Top Down Design

Part 1: Due Saturday, March 26, by 11:59pm (done with your assigned partner)

Part 2: Due Saturday, April 2, by 11:59pm (done individually)

### Goals

• practice using Top-Down Design to design a complex program

• write a complex program, with multiple functions, from scratch

• practice with interactive implementation and testing of functions in a large program

• practice using file I/O

### Notes

Please read through the entire lab before starting!

This is a two-part lab, split over two weeks. You have two weeks to complete the full program. The first week is for the design, and the second for the full program. The first part you will do with a partner, and the second part you will do on your own:

• Part 1: for the first week you will work with a partner and focus on using top-down design to create the overall structure for the program. Once your proposed structure has been reviewed and approved by your professor, you will move on to the second part.

• Part 2: is to be done individually use a bottom-up implementation to complete the full program based on your design in Part1.

Your initial top-down design is due this Saturday (March 26) and the full implementation the following week (April 2). We highly recommended that you submit your top-down design as soon as is possible so that we have time to give you feedback before you begin your full implementation. If you submit your design on the last day at midnight, it might take us a few days to get to it and send you comments.

### Part 1 Partners

The list of partnerships is on the EdStem page: Lab 8:Part1 Partners.

Please read the following guidelines for lab partnerships for information about how to best collaborate with a partner on lab assignments.

## 1. The Game of Melty

Melty is a word guessing game that uses a snow-person (named Melty) to simulate the number of guesses the player has left to figure out what the word, guessing a single letter at each turn. The goal of the game is for the player to correctly guess the word before Melty melts away. With each incorrect guess, Melty melts a bit more, until after 8 incorrect guesses they are just a puddle and the player loses.

In implementing this game the computer starts by picking a random word from a file of words. The word will initially be shown with a dash, '-', in place of each letter. With each round of play, the player guesses a letter that they think may be in the word. If the player guesses correctly, then for subsequent rounds the letter will be shown in place of the dashes in the word left to guess. The rounds of play end when either Melty melts (the player makes 8 incorrect letter guesses), or when the player solves the puzzle (guesses all letters in the word).

### 1.1. Sample Output

Take a look at some Sample Output from a run of a complete program to get a sense of how the game is played.

Note that the ascii drawing of Melty is optional (but it is a fun part to add if you have time).

### 1.2. Requirements

Your Melty program must support:

• Get a randomly chosen word from the file of words. The word file you will use is `"/usr/local/doc/wordfile.txt"`. We will discuss file I/O in class on Monday.

• Display the puzzle with guessed letters filled and `-` for un-guessed letters at the start of each round.

• Display the the number of incorrect guesses left at the start of each round.

• Optionally draw the state of Melty at the start of each round.

• The user can enter either an upper or lower case character for a letter guess.

• Tell the user that they have already guessed a letter, and let them pick again.

• Print out a message indicating if the user guessed a correct letter in the word or not.

• End the game when the user guesses all the letters in the word or when the player runs out of guesses.

• Print out a message at the end of the game indicating if the player won or lost, and print out the word if not.

• Use good modular design, including at least 5 different function-worthy functions.

• All functions should have complete comments, and use meaningful variable and parameter names

• Be robust to some invalid input, such as detect and handle if the user enters an invalid character value as a choice (e.g., "hello" or "6")

## 2. Part 1: Top-Down Design

You will start this lab by designing your solution using Top-Down design. You and your partner should complete your top-down design, submit it, and get faculty feedback on it before you each start individually on the full implementation.

### 2.1. Steps for this part:

• create `design-melty.py` first

• when you have a working design you and your partner should (for more details on these steps, see: Section 2.3):

1. make sure you both have the file version of our `design-melty.py` file

2. both run `handin21` to submit it

3. both send an email to `tdd@cs.swarthmore.edu` notifying the professors letting them know your `design-melty.py` is complete and submitted.

• After you have heard back from use with comments on your design, either:

1. work together to re-do parts of your design and resubmit for further review (follow step 2 above)

2. or move on to working by yourself on Part2: the full implementation.

### 2.2. Requirements for TDD

• `main()` should call the top-level functions in your design, in the appropriate order, and with arguments that match parameters. Return values should be assigned to local variables in `main` even if `main` doesn’t do anything with them yet.

• All functions be stubbed out with parameters, a block comment, and a return statement. They don’t need to do anything yet, except possibly call other functions.

• If a function returns a value, in the stubbed out version have it return some value of the correct return type. For example, for a stubbed out version of a `sqrt` function, I might have it `return 0.0` and then later when I implemented the function, change the return statement to return the correct value.

Here are some examples of function stubs: example function stubs

• Your design should contain several functions, 5 at a minimum. Each should be function worthy (not a trivial task), and each should demonstrate encapsulation (have a clearly defined purpose or functionality).

• Your `design-melty.py` design should run without syntax errors (i.e. each function called from main should work even if it doesn’t do much more right now than return).

### 2.3. Submitting your TDD

1. Both you and your partner need the same copy of your `design-melty.py` to start with Part 2. As you develop your TDD, we encourage you to share your latest copy as you go, but prior to submission you should make sure to share your final TDD `design-melty.py`. Here are two different ways to share the lastest version of your desgin file:

1. email and mv: email the file to each other as an attachment in gmail. On our system, if you download a file in a browser, by default it is saved into your `~/Desktop/` subdirectory. You can then move the file into your `cs21/labs/08` subdirectory using the `mv` command:

``````ls -l ~/Desktop/desgin-melty.py   # check that you correctly download the file
cd ~/cs21/labs/08                 # cd into your 08 subdirectory
mv ~/Desktop/design-melty.py ./   # mv the file from your ~/Desktop subdirectory
# mv will ask if you are sure, type y if so``````

To check if `mv` was successful you can see if the modification date on the file is right now by running `ls -l`. It is also good to just open the file in `vim` to check that it is the currrent version. If so, go ahead and submit using `handin21`. If not, try the `mv` command again.

``````ls -l    # this should list the current time with design-melty.py
vim design-melty.py  # check that this is the latest version``````
2. scp: use `scp` to copy the file from one of your accounts to the other (note: both you and your partner need to be in the lab together to do it this way). From the partner’s account with the most recent version of `design-melty.py`, (we will call this person partner1), run `scp` to copy the file into your partner’s account (partner2). In a terminal on partner1's machine you will `scp` the file to partner2's account (in the `scp` command replace `partner2username` with their username, and partner2 needs to enter their password with `scp` prompts for a password):

``````cd ~/cs21/labs/08      # partner1: cd into your 08 subdirectory

# at this point scp will ask **partner2** to enter their password``````

If successful partner2 now has the latest version of your `design-melty.py` file in their `~/cs21/labs/08` subdirectory. They can verify this by checking that the modification date on the file is right now by running `ls -l`. It is also good to just open the file in `vim` to check that it is the currrent version. If so, go ahead and submit using `handin21`. If not, try one of these two ways of sharing the file again.

``````ls -l    # this should list the current time with design-melty.py
vim design-melty.py  # check that this is the latest version``````
2. Then both you and your partner should run `handin21` to submit your joint `design-melty.py` file for grading

3. Finally, both you and your partner should send an email to `tdd@cs.swarthmore.edu` notifying the professors that you have submitted your desgin for grading.

After you submit one of the professors, not necessarily the one from your lecture, will email you feedback on your design. We may ask you to re-do some of it, we may ask you to redo and resubmit, and we may okay it, in which case you are ready to move on to Part2 that you will complete individually.

## 3. Part 2: Implementation

Once your top down design has been okayed by your professor, you can start working individually on the implementation of your melty program in `melty.py`.

Begin with a copy of your TDD solution as a starting point for your full implementation. To do this copy the `design-melty.py` to `melty.py` in one of two ways (the first is safer, but either way is fine):

1. Open `melty.py` in `vim`, then in ESC mode type `:r design-melty.py` to copy the contents of `design-melty.py into `melty.py`.

2. In the terminal, using the `cp` command to copy `design-melty.py` to `melty.py`:

``$cp design-melty.py melty.py`` ### 3.1. Implementation Requirements In addition to supporting the primary requirements of the program listed Section 1.2 your implementation should: • `main` should just reflect the high-level steps of your program. Details of steps should be encapsulated in functions called by `main`. It is okay if main contains very high-level game playing loop, but often it is better to have this in a separate function. They key is that `main` is very simple, easy to read, and reflects the big steps of the program. • use meaningful names for functions, variables and parameters • be robust to some bad input • be well commented • not have any wrapped lines (use the line continuation character `\` to handle any stmts that are longer than 80 columns ### 3.2. Word File This is the word file your program should use: `"/usr/local/doc/wordfile.txt"`. Its format is a single word per line. For example, here is a very small file of 4 words in this format: ``````hello one another goodbye`````` You can also open the file in vim to see how it is organized: ``vim /usr/local/doc/wordfile.txt`` • Look at some of the example file I/O code from Monday’s class for how to read in one or more of the words from this file. • Look at some of the random libary functions to find one that might be helful for choosing a random word from the words in this file. ### 3.3. Tips • Use incremental implementation and testing as you go. Implement all or part of a function, and add a test call to it to test it for correctness. Then add a bit more. • You will need to keep track of the puzzle solution (the word chosen), the parts of the puzzle that have been guessed and have not yet been guessed, and the set of letters already guessed. Using separate lists for these three will yield less complicated code. • You can convert a string to a list of characters (single character strings) like this: `````` word = "hi there" lst = list(word) # convert a string to a list print(lst) # ['h', 'i', ' ', 't', 'h', 'e', 'r', 'e']`````` • random library functions ## 4. Extra Challenge(s) Don’t try any of these until your solution to the main problem is complete, tested, and well-commented. Here are some extra things you can try adding: • Add the ascii drawing of Melty at each round (like in the sample output). You can draw Melty to look different from ours, but design yours so that Melty has 8 parts, one of which is removed after each incorrect guess. For ascii drawings you need to think about the fact that once you have printed out the first line of the drawing, you cannot go back later and print out something on that line. For example, for our melty the first thing we do is print the top of Melty’s hat, and the second call to print prints the first line of the two sides of Melty’s hat, and so on: `````` print(" -----") # print top of Melty's hat print(" | |") # print next part of Melty's hat`````` In solving this, think about how to choose to draw certain parts or not based on the number of guesses left (don’t write 8 or 9 completely separate functions to draw Melty in every different melted state separately). • Add an option to allow the user to quit at any time (after each round). • Add an option to allow the user to guess the puzzle (without guessing each letter one at a time). If they guess correctly, they win. If not, Melty immediately instantly melts and they lose. • Add some other input files that include short quotes or phrases, one per line. Have the user guess the phrase a letter at a time. For this, you will need to display the phrase with spaces between each word. If the phrase has punctuation characters, you should display the punctuation. For example, if the phrase is "Aspire to inspire, before we expire." you would display as: ` - - - - - - - - - - - - - - , - - - - - - - - - - - - - -.` ## 5. Answer the Questionnaire Each lab will have a short questionnaire at the end. Please edit the `Questions-08.txt` file in your `cs21/labs/08` directory and answer the questions in that file. Once you’re done with that, you should run `handin21` again. ### Submitting lab assignments Remember to run `handin21` to turn in your lab files! You may run `handin21` as many times as you want. Each time it will turn in any new work. We recommend running `handin21` after you complete each program or after you complete significant work on any one program. ### Logging out When you’re done working in the lab, you should log out of the computer you’re using. #### When Remotely logged in When you are ssh’ed into the CS labs, first quit any applications you are running, like `vim`, then simply type `exit` at the prompt in your terminal window to disconnect. #### When Physically logged in When you are in a CS lab logged into a CS machine. First quit any applications you are running, like the browser and the terminal. Then click on the logout icon ( or ) and choose "log out". If you plan to leave the lab for just a few minutes, you do not need to log out. It is, however, a good idea to lock your machine while you are gone. You can lock your screen by clicking on the lock icon. PLEASE do not leave a session locked for a long period of time. Power may go out, someone might reboot the machine, etc. You don’t want to lose any work! ## Resources ### Programming Tips As you write programs, use good programming practices: • Use a comment at the top of the file to describe the purpose of the program (see example). • All programs should have a `main()` function (see example). • Use variable names that describe the contents of the variables. • Write your programs incrementally and test them as you go. This is really crucial to success: don’t write lots of code and then test it all at once! Write a little code, make sure it works, then add some more and test it again. • Don’t assume that if your program passes the sample tests we provide that it is completely correct. Come up with your own test cases and verify that the program is producing the right output on them. • Avoid writing any lines of code that exceed 80 columns. • Always work in a terminal window that is 80 characters wide (resize it to be this wide) • In `vim`, at the bottom left in the window, there is an indication of both the line and the column of the cursor. ### Function Comments All functions should have a top-level comment! Please see our function example page if you are confused about writing function comments. ### Are your files in the correct place? Make sure all programs are saved to your `cs21/labs/08` directory! Files outside that directory will not be graded. ```$ update21
$cd ~/cs21/labs/08$ pwd