---
title: Project 2 Spring-2024
tags: Projects-S24, Project 2
---

# Project 2: Frog Maze Craze

## Deadlines

**Project Released**: Wednesday, March 13, 2023
**Design Checks**: Tuesday, March 19 & Wednesday, March 20. Check your email to sign up for a design check with your design check TA. Remember to include your project partner in the Google Calendar invite when scheduling your design check!
* One group member must submit the design check to Gradescope at least 24 hours before meeting with your design check TA. Ensure both partners are added to the submission.

**Final Handin Deadline**: Friday, April 5, 2023, at 11:59 PM

:::success
This is a two-week project, and you should have ample time to work on both the design check and project implementation. Do start early!
:::

## Project Overview
<!-- {%youtube gMrVSYP0fr8 %} -->
[**View a video demo of the game here!**](https://drive.google.com/file/d/1hiPBoNSprbqG7Xu54ZzP95a7mc3FanKa/view?usp=sharing)

In this project, you will be creating a maze game. The user will navigate a frog around the maze using key presses and/or mouse clicks. The frog will be able to move through the water tiles, but is unable to move through grass. In other words, the grass and water tiles serve as maze walls and paths, respectively. Along the water, the frog can run into special items (widgets), such as insects that completely restore the frog's stamina, worms that gives them a small stamina boost, ducks that deplete their stamina, or lily pads (representing portals) that allow the frog to teleport. If implementing widgets, the frog's stamina should be shown as the yellow bar on the right. The goal: Help the frog safely make it back to its friend at the end of the maze.

This project has two broad components! You will write the code to:

1. "Render" (draw) the maze, its items, and the frog
2. Represent the logic allowing the (human) player to use the keyboard and/or mouse to navigate the frog around the maze

To configure the maze, we will use tables in a new way: you'll use information from a spreadsheet to set up where the grass and water should be. Your program will read in these sheets and use them to create the actual background maze image and initial widget/portal placements. The gameplay itself will be implemented with a **reactor** (as we did in Lab 2 and have been doing in lecture).

The project offers different levels of completion, roughly corresponding to whether your goal is to earn an A, a B, or a passing grade on the project. The [grading section](#Grading) further down goes into the details.

*After all of the design checks are done, we will provide our solution to the design check phase, which you can use as you wish in producing your implementation. You are **not** required to use our solution if your own is functional!*

### Project Learning Goals

This project applies what we've been learning about lists, recursion, and datatypes. It exercises your ability to detect what information does and doesn't change over time in a program. It has the side benefit of showing you how animations can be built, and of showing how tables can be useful for more than just storing data. Here are the specific skills you will practice.

- Creating and using your own datatypes.
- Using recursion to process various types of lists.
- Breaking down complex goals into discrete, solvable tasks.
- Using tables for code configuration rather than as datasets.

#### What class material does this build on?

This project builds on reactors (from lab 2) and the recursion skills that you practiced in homework 5 and lab 6. We will refresh the concept of reactors and talk about designing our own Datatypes for them in lecture on March 11.

### Game Details
#### Maze
The entire maze should be surrounded by one layer of grass (except at the end location), so you don't have to deal with the frog moving outside of the maze. This also makes it clear to the human player where they need to navigate to in order to complete the game.

The grass and water tiles are 30x30 pixels (you will need this information to convert coordinates in the grid to coordinates in Pyret for `place-image`). All other game objects, including the frog, widgets, and portals, are 24x24 pixels.

#### The Player and Character
The position of the player in the maze is represented with an image of the frog. The human player moves the frog using the `W` (up), `A` (left), `S` (down), and `D` (right) keys. The frog cannot move through grass, but can move through water.

#### Items
There are two kinds of items that can be placed in the maze: ++widgets++ and ++portals++. Widgets are items a frog can collect that affect its stamina. Portals are tools a frog can use to teleport around the maze.

There can be an arbitrary number of these items placed on the maze. Items are picked up when the player moves into their cells (meaning they disappear subsequently). Widgets are immediately consumed, and portals are "held on to" until use. Multiple portals can be collected; only one is used each time the player teleports.

You will implement either ++widgets++ or ++portals++ into the game. **You only need to implement ONE of these to get full credit**. You may do both if you want, but you will not get extra credit. Either option is challenging in its own way; we do not think either is significantly easier than the other.

#### Starting, Winning, and Losing
The frog will start at a location of your choosing. The information of where they start should be hardcoded through named constants in your code.

The player wins the game upon reaching the **princess** ![princess](https://code.pyret.org/shared-image-contents?sharedImageId=1JzZiAQE_PwONvsTovKHdPUmi-bOxhmFW
) at an exit location that you set. This information should also be hardcoded through constants.

In the **widgets** version, the player loses the game if the frog runs out of stamina. If you implement **portals**, the player doesn't have to worry about losing.

Upon winning or losing, the game can simply stop. You may also choose to somehow inform the player that they have won or lost, but this is not required and will not give any extra credit.

## Phase 1: Design Check and a Basic Reactor

For this project, you will write a bit more code than you did for the project 1 design check. Our goal with the design check is for you to (1) design your data structures, (2) make sure you have a basic reactor infrastructure working, and (3) have viable plans for building out the reactor to the full version you are implementing.

For design check, you will hand in an initial `game-s24.arr` file. Submit this to Gradescope at least 24 hours before your design check starts.

We recommend doing the questions in order as much as possible, as each question will help you think about the next.

**Task 0:** Make a copy of the [project starter file](https://code.pyret.org/editor#share=1RCCCzFxacsTPUD5FmAvpX5j9ZqAez5QL&v=78aeaeb).

**Task 1:** Decide whether you want to implement widgets or portals.

**Task 2:** Watch our demo video and figure out what information **changes over time** as the game is played. Just write this down in prose (no code) in a block comment in your Pyret file.

**Task 3:** In `game-s24.arr`, organize this information into a Pyret `data` block that captures the state of the game (call it `GameState`). You will end up using a combination of lists and other `data` blocks in your design. Include whichever of widgets or portals you've chosen.

*Hint: Figuring out the datatype for this is one of the more challenging parts of this assignment. Look at the things you identified for Task 2: you'll end up making datatypes for objects in the animation (with their attributes), collections of similar objects, and datatypes that gather objects and collections into single "concepts" within the game. Expect to need some time here. If you aren't sure what makes the most sense, come up with a couple of different ideas and review them with a TA.*

**Note:** your `data` block should contain ONLY information that changes about your animation over time. An element that doesn't change will go into the background in Task 5.

**Task 4:** In code, write a concrete example of `GameState` data for an initial configuration of your game. Don't worry about information that will eventually come from one of the Google Sheets, and don't worry about whether this `GameState` errors -- just make SOME example for now.

**Task 5:** Build the `BACKGROUND` image for a maze (the part of the image that does NOT change over time). Don't worry about including the widgets or portals. Your `BACKGROUND` image should be built using a function and `maze-grid` – you should **not** be manually constructing the maze.

Note: The maze design will be imported as a list of lists, such as the following ("x" is a wall/grass, "o" is open space/water):

small-maze = 
  [list: [list: "x", "x", "o", "x"],
         [list: "x", "o", "o", "x"],
         [list: "x", "o", "x", "x"],
         [list: "x", "o", "x", "x"],
         ] 

While later in the project you will read in such a list of lists from a Google Sheet, for this task you are only required to build a maze background image from a small example. Use `small-maze` for this.

How can you do this? Notice that the list of lists resembles a grid; the maze background will also be a grid, just made from image icons (with a "grass" icon in place of "x" and a "water" icon in place of "o").

In lab, you practiced aggregating a list into a single image. For homework 1, we aggregated multiple images into one image. **This question has you apply and combine these ideas; if you come to hours or post on Ed, talk through your proposals for doing this, rather than simply asking us how to get started.**

The [Pyret Image documentation](https://pyret.org/docs/latest/image.html) will be helpful for this! You'll have to decide which functions should be used for aggregating images.

**Task 6:** Set up a simple reactor that moves the frog across the background image when the human player presses a key. At this point, it is fine if your frog walks on grass cells (just get a basic reactor running). Reference Task 3 to set up your initial `GameState` configuration.

**Task 7:** Make sure you can load the configuration data from Google Sheets. Make a copy of a [configuration spreadsheet](#Configuring-the-Maze-in-Google-Sheets). In Google Sheets, you can do this by clicking `File > Make a Copy...`. Then:
- share the spreadsheet with your partner
- give "Anyone with the link" the ability to view the spreadsheet (you have to go into the Advanced sharing menu to do this).
- insert the ID of your spreadsheet into the name `ssid` in your `game-s24.arr` file
- take the comment marks off the definitions of `maze-grid` and `item-table` and make sure your file runs.

Then look at `maze-grid` and `item-table` to get an idea of what they look like.

From here, we want you to plan key parts of the rest of the solution, so you can review them with your design-check TA.

**Task 8:** Write a plan for how you will add the widgets or portal images to the maze. You may include this in a block comment in your code file.

**Task 9:** In another comment, write out a plan or general sketch of how the `key-pressed` function should work. Pick one of the four keys (`W`, `A`, `S`, `D`) and write out the tasks (3-5 one sentence bullet points) needed to compute the new `GameState` based on the current `GameState`. What are some edge cases that you'll need to consider? Write a single `where` test case on a small `GameState` for the key that you planned out.

**Task 10:** Plan how to implement widgets or portals.

- **If you are implementing widgets**: write out a plan for what should happen to the `GameState` when the frog lands on a square with a specific widget (pick whichever one you want to handle). Add a `where` example that corresponds to your plan.
- **If you are implementing portals:** The reactor `mouse-clicked` function, tied to [`on-mouse`](https://pyret.org/docs/latest/reactors.html#%28part._on-mouse%29), takes in the current `GameState` value, the `x` and `y` value of the position of the mouse event, and a `String` that represents the name of the mouse event (in our case, `button-down`, which essentially means a mouse click). Write out the tasks needed to compute the new `GameState` based on the current `GameState` if the mouse has been clicked. Write a corresponding **simple** `where` example for `mouse-clicked`.

## Phase 2: Implementation Details

### Configuring the Maze (in Google Sheets)

The game will be populated based on your copy of one of the following spreadsheets (depending on whether you want to implement widgets, portals, or both):

- Widgets spreadsheet: [link](https://docs.google.com/spreadsheets/d/1tbcj6eeuIdrXFlSWFQy9RuW1XJ0RY33d9kLsMCrvRaU/edit?usp=sharing)
- Portals spreadsheet: [link](https://docs.google.com/spreadsheets/d/1RmEN_5BGMqz5kwnc4NL1Vj6E0426mmW1lpnCXyezzOE/edit?usp=sharing)
- Both items spreadsheet: [link](https://docs.google.com/spreadsheets/d/1A2MPpOqk_IQKfRd_x6g5m5We73w0XAvb1Vre2X9oSCE/edit?usp=sharing)

Each spreadsheet has two sheets: `maze-layout` and `items`.

- The `maze-layout` sheet determines which parts of the maze are grass and which are water. This determines where the frog can go – the frog can go on water but cannot go on grass. "x" corresponds to a grass tile, and "o" corresponds to a water tile.
- The `items` sheet contains a list of items that will be placed on the maze. The $x$ column is the distance from the left side of the screen, and the $y$ column is the distance from the top of the screen. (These distances are in terms of the grid labels in the maze, not pixels for built-in Pyret image operations).

:::info
**Note 1:** Positions are zero-indexed; the row `"Insect", 1, 7, "Insect.png"` corresponds to  being placed in the 2nd column and the 8th row.
**Note 2:** You do not need to do any error checking for items being placed in invalid locations (like on grass or off the maze).
:::

The maze we provide in the Google Sheet is 35 squares per "row" and 19 squares per "column" (19x35), but you can add or remove rows, columns, and items as you please and make the maze your own! **If you change the number of columns in your maze, replace the call to `load-maze` in the starter code with a call to `load-maze-n`**. The latter is the same as `load-maze` except it has a second parameter which is the number of columns to load.

:::warning
Do not adjust or rescale the sizes of the images that we provide. Parts of the support code will break if you do.
:::
<!--
| Name | Image |
| -------- | -------- |
| Maze Sheet |  |
| Items Sheet| 
-->

### Reactor Documentation

You have seen the reactor properties `init`, `to-draw`, and `on-key` before. If you are implementing portals, you will also need to use the `on-mouse` function, which works similarly to the `on-key` function; check out [the `on-mouse` documentation](https://www.pyret.org/docs/latest/reactors.html#%28part._on-mouse%29) for more.

You can refresh yourself on reactor properties [here](https://www.pyret.org/docs/latest/reactors.html). You may also want to look at your code or the code files from recent lectures with reactor examples.

### Converting mouse clicks to maze coordinates (portals only)

The reactor `on-mouse` function takes in $x$ and $y$ coordinates that do not directly correspond to which row and column in the maze the user clicked on. Because of this, `get-maze-index` is a function (provided in the source code) that takes in the coordinate that is input to `on-mouse` and converts it to a game grid coordinate. For example, if the `x`-coordinate clicked is 334, `get-maze-index(334)` returns 11 (for the 12th column).

### Implementing Widgets

If you implement widgets, the frog needs to have *stamina*. Stamina is a measure of energy often used in video games. In this game, the frog's stamina depletes by moving. If the frog runs out of stamina, it's game over.

There are three things you can encounter in the maze: insects, worms, and ducks.
- Finding **worms**  heals the frog for some fixed amount of stamina.
- Finding **insects**  replenishes the frog's stamina to its original value.
- Finding **ducks**  reduces the frog's stamina to some low, fixed amount. You should pick this number.

For example, if the frog's stamina is 20 and they move onto a duck, they may move down to 7 stamina. Then moving onto a worm may heal them to 7 + 8 = 15 stamina, and finding insects will heal them to their original stamina (say, 30). **Normal movement reduces stamina by 1 per cell.**

There should be a visual indication of the frog's stamina. In our demo, this is done via the yellow bar on the right.

### Implementing Portals

The portals in this maze will be represented by the **lilypad**  image. The frog can carry any number of lilypads, but starts with no lilypad. When the frog has a lilypad and the user clicks some square on the screen, the frog will move there *as long as the cell is within some reasonable range of the frog's current location.* You can choose this range, but make sure it doesn't allow the player to easily teleport to the end of the maze!

Each lilypad can be used only once. Your game screen should have some visual indication of how many portals the frog has (simply a number using the Image library's [`text`](https://www.pyret.org/docs/latest/image.html#%28part._image_text%29) function is fine).

To compute how far the human player is trying to move the frog, you can use the standard formula for computing distance between two points (see the spoiler below if you need a refresher on computing distance). In your game, if a player with a lilypad clicks on a cell, and the distance between the current and clicked cells is within the threshold you choose, the frog moves to the new cell and uses up a lilypad. If the distance is larger than the threshold, nothing changes (the frog stays in the same place and keeps the lilypad for another try).

:::spoiler The Distance Formula

The distance formula is based on the differences in x-coordinates and differences in y-coordinates between two points. Call the change in the $x$-coordinate $\Delta x$ and the change in the $y$-coordinate $\Delta y$:
$$D = \sqrt{\Delta x^2 + \Delta y ^ 2}$$

For example, if the player is at $(3, 8)$ and wants to move to $(6, 4)$, $D = \sqrt{(6 - 3)^2 + (4 - 8)^2} = \sqrt{9 + 16} = 5$. This is a "birds-eye view" of distance.
:::

## Approaching This: Work on One Feature at a Time

The key to tackling a larger assignment like this is to build the features up gradually. For example, get the game working on just basic functionality before adding more advanced features. What might that mean here?

1. Implement a version with just the grass (no widgets or portals), such that the player can move around the maze while respecting the grass barriers.
2. Read in the items (insects, lilypads, etc) from the Google Sheet, store them in your data structure(s), and make them show up when you draw the GameState.
3. Get the items to disappear after a player visits their cells.
4. Make the game handle the items (modifying stamina or teleporting).

These phases correspond to the grading levels for the project (see the Grading section below). You can pass the project even if you don't get beyond phase 1.

*We strongly recommend saving a copy of your file after you get each stage working, just in case you need to get back to your last stable version (practicing programmers do this all the time).*

## Grading

#### Testing
Since there are many functions that will be written for this project, ++we will only be requiring minimal testing for all functions that are not critical functions.++ In an ideal world, you would thoroughly test all functions; however, we would rather see you test one or two functions really well (to show you understand the concept) and others partially, rather than only doing partial testing or no testing at all for all functions, especially critical functions.

Because of this, **we will grade (1) minimal testing (>= 2 test cases) for non-critical functions that output things other than an Image, and (2) your thorough testing (try to hit as many tests of edge cases as possible!) for the function that moves the character** (the one you use as `on-key`, or `on-mouse`). Test this function thoroughly, covering as many cases as you can. Regarding your other functions, write as many tests as you think you need to be comfortable with it working - but include at least 2. You do **not** need to write tests for functions outputting an Image.

Your design, testing, and clarity grades will not be based on your functionality grade. Functionality will be weighted more heavily in your final grade for this project in particular. Here is what we're looking at when grading functionality:

#### Minimum Functionality:
- A character that moves in response to key presses, moving full maze-cells at a time.
- Player cannot walk on grass cells.
- Game stops/ends when the character reaches a certain destination (princess).

#### Mid-tier functionality:
- All above.
- Widgets or portals are rendered on the maze.
- If doing widgets: your character must have stamina that depletes upon moving. The widgets do not need to be functional for mid-tier functionality. Upon reaching 0 stamina, the game should end.
- If doing portals: upon picking up a portal, your character can teleport. There does not need to be a limit on the portal range or the number of times the player can teleport for mid-tier functionality.

#### For full functionality:
- All above.
- If doing widgets: insects bring the character to full stamina; ducks bring the character to a low stamina; worms heals for some amount; items disappear when walked over.
- If doing portals: there is a limit to how far the character can teleport and how many times a portal can be used.

## Reflection

This project was designed to give you practice with organizing and manipulating structured data. Answer the following questions about these topics in a block comment at the bottom of `game-s24.arr`.

1. Our support code represented the maze layout (grass vs water) as a list-of-lists of strings, rather than a table. What were the advantages and disadvantages of this choice?
2. In this project, you worked with the maze layout in three formats: the Google Sheet with the configuration of walls, the list-of-lists version, and the image itself. For each representation, briefly describe what it is good and bad for.
3. If you used our design check solution, describe what you learned by comparing your own proposed datatypes to the datatypes in our solution.
4. Describe one key insight gained about programming or data organization from working on this project. Each partner should answer this separately.
5. Describe one or two misconceptions or mistakes that you had to work through while doing the project. Each partner should answer this separately.
6. State one or two followup questions that you have about programming or data organization after working on this project. Each partner should answer this separately.

:::info
Block comments are written with `#|` and `|#`:

#|
  this is a block comment.
  with multiple lines!
  yay!!
|#

:::
## Handin
Hand in `game-s24.arr` on Gradescope.

## EdStem and Feedback

- [EdStem](https://edstem.org/us/courses/54800) can be your friend for this Project!

<iframe src="https://forms.gle/WPXM7ja6KwHdK8by6" width="640" height="372" frameborder="0" marginheight="0" marginwidth="0">Loading…</iframe>