Unscramble: A Word Game

In this assignment, you will write functions to implement a puzzle game that requires the player to use a number of simple moves to reconstruct a scrambled word.

Goals of this Assignment

• Use the Function Design Recipe, Download Function Design Recipeto plan, implement, and test functions.
• Write function bodies using variables, numeric types, strings, and conditional statements. You can do this whole assignment with only the concepts from Weeks 1, 2, and 3 of CSC108.
• Learn to use Python 3, Wing 101, provided starter code, a checker module, and other tools.

The Unscramble Game

Before you begin writing any code, you first need to understand the Unscramble game. Gameplay is described in the paragraphs below, so read carefully!

Game Mechanics

In the game, the player is presented with the scrambled version of a string. The original string has been scrambled by first splitting it into a number of sections, each with the same length, and then rearranging each section randomly, as in Figure 1. The player’s objective is to unscramble the string using as few moves as they can. The player has three moves available: Flip, Shift, and Check. Each move is applied to a single section of the string.

In Figure 1, the section ‘ROCK’ has been scrambled to become ‘KROC’ while the section ‘LAKE’ has been scrambled to become ‘EAKL’.

The sections in the string are numbered 1 to N, where N is the total number of sections. The section length is fixed for each game, and every section will have the same length. For example, given the string ‘treerocklake’ and a section length of 4, section 2 would be ‘rock’.

The Shift move is a circular shift of the string to the left, while the Flip move exchanges the positions of the first and last characters of the string. Both these moves are illustrated in Figure 2 below.

We will use the phrase game state to refer to the current state of the string that the player is trying to unscramble. The Check move is the only move that does not modify the game state. It is used to check if a given section is correctly arranged.

The game allows for 3 modes: Normal, Hint, and Test. Normal mode involves playing the game as we have described above. Hint mode allows the player to receive hints on what sections and moves to choose each round.

Enabling Test mode allows the player to set the correct answer and the number of sections before the game begins.

Gameplay

When the game begins, the player is first asked to choose a game mode. Then, the player is repeatedly asked to provide both:

1. The section number corresponding to the section they want to manipulate. A string with N sections will have its sections numbered 1 to N.
2. The move they would like to apply to the section.

If the player is playing in Hint mode, they will be offered the chance to get a hint for a section to choose, or a move to make on a particular section. Getting a hint counts towards the player’s total number of moves.

The game continues until the player has unscrambled the string. When the game is over, the player’s total number of moves is reported.

Starter code: unscramble_functions.py

This file contains some constants, and a complete docstring (but not body!) for the first function you are to write. You will update this file to include the complete functions that you write, and this is the file you will submit.

Main program code: unscramble_game.py

This file contains the main program code for playing the game. When it is run, the functions that you wrote and put in the unscramble_functions.py file will be called. When you have written all of the functions in unscramble_functions.py, you may play the full game by running unscramble_game.py. You can further test your code by running in Test mode where you are prompted for the ANSWER and SECTION_LENGTH that the game should use. Do NOT make any changes to the unscramble_game.py file, as you will not submit this file.

We do not expect you to understand all of the code in this file at this point in the course.

Checker: a1_checker.py

This file is a checker program that you should use to perform a simple test of your code. See below in the section called CSC108 A1 Checker for more information about a1_checker.py. The checker program also requires the files checker_generic.py and a1_pyta.json. You do not need to do anything with these files, other than keep them all in the same folder.

What to do

In the starter code file unscramble_functions.py, complete the following function definitions in the table below. Use the Function Design Recipe. Download Function Design Recipethat we have been learning in class, and write complete docstrings for each function.

Using Constants

The starter code in unscramble_functions.py starts with the definition of some constants. Your code should make use of these provided constants. If the value of one of those constants were changed, and your program rerun, your functions should work with those new values. We will test your code using different values for the various moves and modes by updating the values of the constants - your code should still work with these updated values! The one exception to this is the constant HINT_MODE_SECTION_LENGTH. This constant will always be set to 3 and your functions only need to work for this value. (We are constraining this value in order to make the assignment difficulty level appropriate for this stage in the course.)

Your docstring examples can use the values of the constants in the provided starter code, and do not need to change if we change the values of the constants.

Preconditions

When writing your functions, you may always assume that: 1. the game state is a valid scrambling of the answer, and 2. both the game state and answer can be evenly split into sections with the given section length. You must not make any other assumptions (e.g. you must not assume all characters are uppercase) other than this and what is given below in the table for each function.

Regarding preconditions: 1. You do not have to write any of the preconditions into the docstrings for this assignment, and 2. You can not assume any preconditions other than what we already mention about the type contracts and parameters in the table below.

What NOT to do

Your unscramble_functions.py file should contain the starter code, plus the function definitions specified above. The functions you write must not include any calls to functions print or input. Also, do not include any extra code outside of the function definitions, and do not import any modules.

CSC108 A1 Checker

We are providing a checker module (a1_checker.py) that tests two things:

• whether your functions have the correct parameter and return types, and
• whether your code follows the Python and CSC108 style guidelines.

To run the checker, open a1_checker.py and run it. Note: the checker file should be in the same directory as your unscramble_functions.py, as provided in the starter code zip file. You can find a demo of the checker being run in the Week 3 Prepare exercises on PCRS. When you run your own checker, be sure to scroll up to the top and read all messages.

If the checker passes:

• Your code follows the style guidelines.
• Your function parameters and return types match the assignment specification. This does not mean that your code works correctly in all situations. We will run additional tests on your code once you hand it in, so be sure to thoroughly test your code yourself before submitting it.

If the checker fails, carefully read the message provided:

• It may have failed because:
• you are missing one or more functions,
• one or more of your functions is misnamed,
• one or more of your functions has the incorrect number or type of parameters, or
• one or more of your function return types does not match the assignment specification, or
• your .py file is misnamed or in the wrong place.

Read the error message to identify the problematic function, review the function specification in the handout, and fix your code.

Make sure the checker passes before submitting on MarkUs.

Running the checker program on MarkUs

In addition to running the checker program on your own computer, run the checker on MarkUs as well. You will be able to run the checker program on MarkUs up to 8 times every 24 hours. This can help to identify issues such as uploading the wrong file.

First, submit your work on MarkUs. Next, click on the “Automated Testing” tab and then click on “Run Tests”. Wait for a minute or so, then refresh the webpage. Once the tests have finished running, you’ll see results for the Style Checker and Type Checker components of the checker program (see both the Automated Testing tab and results files under the Submissions tab). Note that these are not actually marks – just the checker results. This is the same checker that we have provided to you in the starter code. If there are errors, edit your code, run the checker program again on your own machine to check that the problems are resolved, resubmit your assignment on MarkUs, and rerun the checker on MarkUs.

Marking

These are the aspects of your work that may be marked for A1:

• Coding style (20%): Make sure that you follow Python style guidelines that we have introduced and the Python coding conventions that we have been using throughout the semester. Although we don’t provide an exhaustive list of style rules, the checker tests for style are complete, so if your code passes the checker, then it will earn full marks for coding style with one exception: docstrings may be evaluated separately. For each occurrence of a PyTA error, a 1 mark (out of 20) deduction will be applied. For example, if a C0301 (line-too-long) error occurs 3 times, then 3 marks will be deducted.
• Correctness (80%): Your functions should perform as specified. Correctness, as measured by our tests, will count for the largest single portion of your marks. Once your assignment is submitted, we will run additional tests, not provided in the checker. Passing the checker does not mean that your code will earn full marks for correctness.

No Remark Requests

No remark requests will be accepted. Before the deadline, you are responsible for running your code and the checker program to identify and resolve any errors that will prevent our tests from running. A syntax error that prevents your code from running could result in a grade of 0 on the assignment – make sure you make use of the checker program!

Going Further (optional, not for marks)

This assignment is designed to be doable with only the concepts we see in the first few weeks of the course. This means that there are a lot of choices we made in designing this system that could be improved on as we learn more concepts. You are encouraged to think about ways in which you could improve the entire system (both the functions and program files) with additional concepts.

You will notice that there is code provided in unscramble_game.py that we have not yet talked about in class. If you are finding this assignment pretty straightforward, we encourage you to figure out how the program code works, and to then think about how to improve it. By the end of this course, you will be able to understand all of the code in the provided functions, and likely even be able to think of ways to improve it! You may also think of better ways to represent the data in the program.

Important: Your code will be evaluated on how it meets the function descriptions above. While we encourage you to think about how to improve the program, do NOT submit these improvements as part of your Assignment 1 submission.

What to Hand In

The very last thing you do before submitting should be to run the checker module on MarkUs one last time. Otherwise, you could make a small error in your final changes before submitting that causes your code to receive zero for correctness.

Submit your unscramble_functions.py file to the Assignment 1 assessment on MarkUs. Remember that spelling of filenames, including case, counts: your file must be named exactly unscramble_functions.py. You can upload your file as many times as you want, and your last submission before the deadline will be marked. Make sure you run the checker in MarkUs one last time and verify it passes so we will be able to test your code.