# Mazes
The goal of this assignment is to familiarize you with functions, including
defining functions, calling functions, and passing values between functions as
arguments and return values. You will write a set of functions to solve a
series of mazes, including a set of helper functions to help with more
complicated mazes.
| Part | Section |
|---------------|-----------------------------------------------|
| 1 (in-lab) | [Practice with Functions](#part1) |
| 1 (in-lab) | [Check-in Instructions](#checkin) |
| 2 (lab/home) | [More functions](#part2) |
| 2 (lab/home) | [Submission Instructions](#submission) |
## Getting started
Create a new project named `Mazes` in the `CSCI051p-Workspace` you
created on your Desktop. You should also double check that you are creating
the project in the right place (Location should be
`/home//Desktop/CSCI051P-Workspace/Mazes`), or you will likely have
trouble finding your files later.
**IMPORTANT: If you are working on a lab machine, you
will need to make sure you select the correct interpreter before you click
create. To do
this, click on the arrow to the left of `Project Interpreter` and selection the
option `Existing interpreter`. Make sure that the Interpret location shown is
`/usr/local/bin/python3.7`.**
Once you have created a project,
download the [starter code](mazes.zip), and unzip the file (on a Mac, unzipping
will happen automatically). You should see a folder named `starter` that
contains three files (`MazesPhysicsEngine.py`, `game.py`, and `mazes.py`) and
two
subfolders (`images` and `levels`). Copy all three files and both folders into
the (recently created) `CSCI051p-Workspace/Mazes` folder. If you don't see all
the new files, ask PyCharm to rescan that folder by clicking the triangle
next to that folder (on the left-side list) to close and re-open it. The newly
added stuff (`MazesPhysicsEngine.py`, `game.py`, `mazes.py`, `images`, and `levels`) should now be visible.
**IMPORTANT: If you are working on your own machine, you will need to install
the `arcade` package before you will be able to run the starter code (but after
you create the project). Follow
the [instructions for installing arcade](install.html) before proceeding.**
Double-click on mazes.py (in the left-side list) to open it in the main editing
window. Then try running it. If you see a gameboard pop up in a new window then
the program is running correctly; stop the program (you should be able to do
this either by clicking the red square stop button in PyCharm or by closing the
window) and proceed.
If things are not
set up correctly, you will probably see an error `ModuleNotFoundError: no module named arcade`.
In this case, you will need to follow the [instructions for installing
Arcade](install.html) before you will be able to proceed. If you have already
tried that and it is still not working, consult a TA or instructor for help.
## Introduction to Mazes
Take a look at the code in `mazes.py`. You should see a
file-level multiline comment at the top (where you should add your name and the
date you finish the assignment), followed by two import statements, followed by
the initialization of a global variable `game`, followed by a function
definition `forward_move`. **IMPORTANT: You should not change any of this code,
other than to add your name and date to the file-level comment. You should only
make changes between the BEGIN STUDENT CODE comment and the END STUDENT CODE
comment.**
Read the docstring comment for `forward_move`. Do you understand what that
function does? Note: You do not need to read (and you certainly don't need to
understand!) the implementation of `forward_move`. You will just need to figure
out what it does so you can call it.
Scroll down below the `BEGIN STUDENT CODE` comment. Here you will see another
global variable definition `START_LEVEL = 0`. This specifies which level to
start on. Leave it as zero for now, but you can change it to higher numbers
later to skip levels you have already solved.
Next, you will see a function definition `solution_0`. Based on reading through
the function definition, what do you think this code does?
Now run `mazes.py` again. You should see the game board. Press enter once. This
will run the function `solution_0`. Did it do what you expected? Based on what
you have learned, how would you move the player up? How would you move the
player left?
You have successfully solved a level if you navigate the player character to
the star. `solution_0` is a correct solution to Level 0, so the player will get
to the goal (the star). After that, you should see a level complete page.
![Mazes: Level 0](images/passed.png)
Note that the level complete page displays the number of steps the player took.
This is the value returned by `solution_0`!
Press enter to proceed to the next level.
## Part 1: Practice with Functions
Your job for Part 1 is to implement solutions to the next three levels of the
mazes game. Note that a solution is only considered correct if it navigates the
player to the correct destination without hitting any walls, and if it returns
the number of steps *successfully* taken while executing the solution function.
#### Level 1
Implement a correct solution to Level 1 by moving the player to the location
of the star. The only way to move the player is by calling the function
`forward_move`, so you will need to make multiple calls to that function in
order to move the player to the correct destination. Your implementation of
`solution_1` should return the number of steps the player *successfully*
took. Note this should be true even if we try to use your solution on a
different game board! This means that you can't just count the number of steps
the player takes when solving level one; you will have to use the return values
from your calls to `forward_move` to calculate the total number of successful
steps.
#### Level 2
Implement the helper function `move`; this function is similar to the function
`forward_move`---it takes two parameters `steps` and `direction`, moves the
player the specified number of steps in the specified direction, and then
returns the number of steps successfully taken---but it is
more flexible than `forward_move`. `move` should correctly handle any integer
number of steps (including negative integers) and any direction that is a
multiple of 90---including a negative number---instead of just 0, 90, 180, or
270. Hint: you will need to call `forward_move` to implement `move`! You can't
just copy paste code from `forward_move`.
Next, use your function `move` to implement a solution to Level 2 in function
`solution_2`. Your implementation should not make any calls to `forward_move`.
#### Level 3
Implement the function `knight_move` following the specification given in the
docstring. Then use that function to implement a correct solution to Level 3
in function `solution_3`. Hint: you might need to also use one call to `move`.
#### Checking In
Find a TA or your lab instructor and demo your solutions to levels 1-3. They
will look over your code, ask you to run your code, and award you points for
Part 1.
This must be completed before leaving the lab.
After that you should start working on Part 2.
## Part 2: More Functions
Your job for Part 2 is to implement solutions to the last six levels of the
mazes game. Note that you can change the value stored in the variable
`START_LEVEL` (at the beginning of the student code section) if you want to skip
levels you have already solved.
#### Level 4
Use the function `knight_move` to implement a correct solution to Level 4
in function `solution_4`. Your implementation of `solution_4` should only
include one call to the function `knight_move`, and it should not include any
calls to `forward_move` or `move`.
#### Level 5
Implement the function `conveniently_useful_s` following the specification
given in the docstring. Then use that function to implement a correct solution
to Level 5 in function `solution_5`. Your implementation of `solution_5` should
not include any calls to `forward_move` or `move`. Note: it is possible to
implement `solution_5` with only one call to `conveniently_useful_s`, where a
call inside a loop is considered one call even if it executed more than once.
#### Level 6
Implement the function `move_and_turn` following the specification
given in the docstring. Then use that function to implement a correct solution
to Level 6 in function `solution_6`. Your implementation of `solution_6` should
only include one call to `move_and_turn`, and it should not include any calls
to `forward_move` or `move`.
#### Level 7
Implement the function `candy_cane_left` following the specification
given in the docstring. Then use that function to implement a correct solution
to Level 7 in function `solution_7`. Your implementation of `solution_7` should
not include any calls to `forward_move` or `move`. Note: it is possible to
implement `solution_7` with only one call to `candy_cane_left`.
#### Level 8
Implement a correct solution to Level 8 in function `solution_8`. Your
implementation of `solution_8` should not include any calls to `forward_move`
or `move`, but you may use calls to any other helper function you have written
for this assignment.
#### Level 9
Take a look at Level 9. This level looks impossible! Open up the file
`levels/level9.txt` and take a look at it. Can you figure out how a game board
is defined? Edit this file to create a new (solvable!) gameboard. Then
implement a correct solution to your new Level 9 in `solution_9`.
#### Coding Style
Make sure that your program is properly commented:
* You should have a multi-line comment atthe very beginning of the file stating
your name, course, assignment number and the date.
* You should include meaningful one-line comments that explain what your code
is doing
In addition, make sure that you have used good style. This includes:
* Following naming conventions, e.g. all variables and functions should be
lowercase.
* Using good (mnemonic) variable names.
* Proper use of whitespace, including indenting and use of blank lines to
separate chunks of code that belong together.
For more detailed descriptions, please review the [Python Coding Style Guidelines](../../python_style.html).
Note that the starter code provides docstrings for all of the functions in this
assignment. Notice how they are written. They include a brief description of
what the function does, followed by specifications for all the parameters
(name, type, and a brief description) and a specification for the return value
(type and a brief description). We will expect you to write good docstrings
for all functions you define for the rest of the semester.
## Part 3: Feedback
Create a file named `feedback.txt` that answers the usual questions:
1. How long did you spend on this assignment? Please include time spent during
lab (including time spent on Part 1).
2. Any comments or feedback? Things you found interesting? Things you found
challenging? Things you found boring?
## Submission
For this lab you are required to submit three files:
- `mazes.py` a python file that solves all ten levels of the mazes game.
- `level9.txt` a text file that specifies the game boare solved by your
solution9 function.
- `feedback.txt` a text file containing your feedback for this assignment.
These should be submitted using
[submit.cs.pomona.edu](http://submit.cs.pomona.edu)
as described in the general [submission instructions](../../submit.html).
Note that we will deduct points if your files are incorrectly names, if
you do not include your name in the correct place, or if you do not include
both files in your last submission. Please double and triple check this before
submitting!
## Grade Point Allocations
| Part | Feature | Value |
|-----------|-------------------------------------------|-----|
| Lab | Check-in | 3 |
| | | |
| Execution | solution_4 | 3 |
| Execution | conveniently_useful_s | 2 |
| Execution | solution_5 | 3 |
| Execution | move_and_turn | 2 |
| Execution | solution_6 | 3 |
| Execution | candy_cane_left | 2 |
| Execution | solution_7 | 3 |
| Execution | solution_8 | 4 |
| Execution | level9.txt | 1 |
| Execution | solution_9 | 2 |
| | | |
| Style | Correctly named files | 3 |
| Style | Files submitted together | 1 |
| Style | Correct file-level multi-line comment | 1 |
| Style | Good use of inline comments | 3 |
| Style | Good use of variable names | 2 |
| Style | Good use of whitespace | 2 |
| Style | Good use of loops and conditions | 3 |
| | | |
| Feedback | Completed feedback file submitted | 2 |