Some Context and Warnings
For this, our last assignment in Pyret, we're going to have you draw on everything we hope you've learned so far: designing data organizations, planning, thinking about constraints, and testing. Expect the code review on this assignment to be a bit more extensive and in-depth in keeping with the flexibility that you have in designing your solution.
Warning: This is not an easy assignment. The complexity comes in the various pieces that you have to put together to build the game. The individual functions are along the lines of what you've written before, but you'll need time to figure out how to put them all together.
- Don't wait until the last minute to start this
- Multiple sessions over multiple days is the way to get this done
- The handout suggests intermediate points to get working before you continue on to additional tasks. Based on many years of experience with a project like this, we very, very (very!) strongly recommend that you work on the assignment in those chunks. If you take on too much at once, it will take a lot longer to piece everything together.
The grading will follow the intermediate checkpoints -- you will be much better off getting some of the intermediate points done well than trying all the parts and have none of them working and of good quality.
Overview
A small studio is making a game about a kid walking to school on a freezing morning. The kid moves around a maze of snowdrifts using the arrow keys. Every step costs the kid a little warmth. Pick up a coat to warm up completely, pick up a scarf to warm up a bit, but avoid the flip-flops or the warmth drops. If the kid runs out of warmth, the game is over. If the kid reaches the school door, the player wins.
The studio wants the game to be easy to configure. The maze configuration and the position of items are arranged in a Google Sheet, so a designer can create a new board without touching the code for the game play. Your job is to take in the Google Sheet data; design a collection of tables, lists, and data to store the current state of the game; and build the game using a reactor. You'll also have to convince your code review TA that your game is high quality and robust against errors (in configuration data or program logic).
Learning objectives
After this assignment, you should be able to:
- Design data structures for a more complex game
- Build a game using a reactor
- Make a case that a program you have developed is robust and unlikely to yield errors as someone plays it
AI and collaboration policy for this assignment
This is an AI-free assignment. We expect you to do the entire assignment on your own to the best of your ability. Think of this sort of like your "coding midterm" in terms of its weight and our expectations.
Setup
Do this assignment in code.pyret.org, not VSCode.
- Make a copy of
maze-game.arr. It has the images, the constants for the sheet, and some given code (including the reactor outline). - We've given you
one
maze example. You are welcome to make your own examples. Copy our
sheet so that you get the format right. You can change the sheet ID
that gets loaded on line 77 (where it defines
ssid). - We will test your game on other boards by changing the sheet id in
ssid, so keep that definition and the lines that use it. - Make a copy of the written answer worksheet and submit the link to it in the worksheet submission form (you can do this before filling anything in).
For lists, you can use map, filter, any, all, length, member, first, append, and .get(n) (the item at position n, counting from 0). For images, you can use beside-list and above-list. Post to Ed if you think you need something else.
Part 1The Game
The maze is a grid of 30x30-pixel cells. Each cell is snow, which the kid cannot walk onto, sidewalk, which the kid can, or the school door, which the kid can also walk onto (and which ends the game; see below). Positions are written as (x, y): x is the column and y is the row, both counting from 0 at the top-left. The kid starts at the cell given by the constants STARTCOL and STARTROW in the starter file, which are (1, 1) for the board we gave you.
Warmth starts at 30. Each step onto a sidewalk cell costs 1 unit of warmth. An attempt to step into snow does nothing: the kid stays put and keeps their warmth. There are three kinds of items, each sitting on a unique sidewalk cell. If the kid steps onto an item, the item is used up (it disappears from the maze) and the kid's warmth changes accordingly to the item (not the usual 1 unit of taking a step):
item | effect on warmth
--------------------------------------------------------
coat | back to the full 30
scarf | +8, but never above 30
flip-flops | drops by half (rounded down)
The game ends when warmth reaches 0 or when the kid reaches the school door, whichever comes first. The kid's warmth is shown as a gold bar on the right edge of the screen.
Game Configuration
Game boards are configured in Google Sheets. A configuration sheet should have two tabs. The maze-layout tab holds one letter per cell: "s" for snow, "w" for sidewalk, and "d" for the school door. The first row and first column of the tab are just numbers that label the columns and rows, to help you find the coordinates of a cell; they are not part of the maze. The items tab holds a table with three columns: name ("Coat", "Scarf", or "Flipflops"), x (the item's column in the maze), and y (the item's row). (0,0) is the coordinate at the top-left of the game board.
Part 2Designing the Data
Here's a demo video of the game. In your worksheet, list the elements and/or their attributes that change while the game is being played, and those that do not.
Develop the data structures (combination of lists, tables, and datatypes) that you need to capture the state (the part that changes) about the game as it runs. Also think about the data structures you want to use to store the maze itself. In your worksheet, explain why you chose these data structures, and name one alternative you considered and why you didn't use it.
Hint: Later you will test your movement code on small mazes, like the one in the next task. Think about how the code that needs the maze will get hold of it.
Create concrete examples of your data for both a maze and a game state (including having items and the kid in the maze). Work with a small maze (say 5 columns by 3 rows).
In your worksheet, write out a list of situations or scenarios that you think you will need to test about how the various parts of this program. Don't write code, just plan out the tests for now.
Checkpoint
We strongly recommend that you review your work to this point in office hours.
Part 3Loading the Maze
The starter file gives you two functions, load-maze-n and load-items, and the lines that call them. (The 25 in the call to load-maze-n is the number of columns in the sheet's maze.) After these lines run, maze-grid will be a list of lists of strings (one inner list per row of the sheet, in order) and item-table will be a table with the items.
Convert the data in maze-grid and the rows of item-table into the data structures you designed in Task 2. Raise a "malformed configuration" error if either the grid or the item table cannot be loaded into your data structures.
Your conversion should work on any list of lists of strings, not just the specific on in the sheet we gave you. This will make it possible for us to test your code on different size mazes.
Part 4Building a Basic Game
First get a basic game working: a kid who moves through the maze and a game that ends at the school door. Ignore warmth and items for now (your game state should still have room for them, from Task 2).
Write the to-draw function: given the game state, produce an image of the game. It shows the maze (the snow, sidewalk, and school tiles in a grid, built from your maze data) with the kid (kid-img) on top. The starter file provides snow-img, sidewalk-img, and school-img for the cells. The kid image is 24x24 pixels, so place its center in the middle of its cell (use place-image).
Hint: Write a separate function that builds the background image from the
maze. Make an image for each row, then stack the row images. The
starter file provides beside-list and above-list,
which put a list of images together horizontally or vertically,
respectively.
Write the two functions that make the game play:
- A function that handles a key press: given the game state and the key, produce the new game state. The arrow keys move the kid up, left, down, and right by one cell. Any other key changes nothing. The kid cannot move into snow.
- A function for
stop-when: the game is over when the kid is at the school door.
The game runs in a reactor. The bottom of the starter file has this skeleton, commented out until you are ready to run the game; fill in each field with your own definitions:
maze-game =
reactor:
init: ..., # your initial game state
to-draw: ..., # a function: game state -> Image
on-key: ..., # a function: game state, key -> game state
stop-when: ..., # a function: game state -> Boolean
title: "Cold-Weather Commute"
end
interact(maze-game)
The reactor calls on-key with exactly two arguments, the state and the key, and to-draw and stop-when with just the state. If one of your functions needs something else (such as the maze), wrap it: on-key: lam(state, key): my-key-function(my-maze, state, key) end. The arrow keys arrive as the strings "up", "down", "left", and "right"; see the reactor documentation.
Note: This game does not use the reactor on-tick function. The game only advances when the human player presses an arrow key.
Hint: To check whether the kid is at the door, you can look up which
letter ("s", "w", or "d") is in the maze coordinate where the kid is
standing. You can extract the letters using the `get` operation on
lists. Specifically, maze-grid.get(y).get(x) returns the letter
at grid coordinate (x,y).
Checkpoint
Get the game working to this point before proceeding: your code should build the maze, the arrow keys should move the kid around, and the game should end at the school. At this point, don't worry about warmth or items. Make sure you have appropriately tested your code to this point (see Part 6)
Checkpoint
This is the minimum-level functionality point. You can pass the project if you skip ahead to Part 6.
Part 5Including Items
Now add the items and the warmth. Your state already has room for both; extend your drawing and your play functions to use them.
Extend your to-draw function: show every item still in the maze (coat-img, scarf-img, flipflops-img, each 24x24 pixels, centered in its cell) beneath the kid, and the warmth bar to the right of the maze.
Helper for this task: place-all
The starter file gives you
place-all(pics :: List<Image>,
xs :: List<Number>,
ys :: List<Number>,
bg :: Image) -> Image It places each picture at the pixel position given by the matching entries of xs and ys (the center of the picture goes there). Later pictures are drawn on top of earlier ones.
For example, place-all([list: kid-img, coat-img], [list: 15, 45], [list: 15, 15], bg) puts the kid at pixel (15, 15) and the coat at (45, 15).
Hint: Note that the Google Sheet gives you coordinates relative to the grid, not in terms of pixels. You'll have to convert grid coordinates to pixels. The fact that each cell is 30 x 30 pixels will help here.
Helper for this task: warmth-bar
The starter file gives you warmth-bar(warmth :: Number, height :: Number) -> Image: a 30-pixel wide bar, height pixels tall, gold from the bottom up to the fraction of INITIAL-WARMTH that warmth is. Put it beside your maze.
Now it's time to adjust the warmth as the kid moves through the streets. Modify your program to have the warmth level decrease by 1 every time the kid takes a step. Ignore the items, just move the kid. Extend stop-when so the game is also over when warmth is 0 or lower.
Checkpoint
This is the mid-level functionality point: if you are short on time, skip the next task and jump ahead to Part 6.
Modify your program again to handle the items. If the kid steps onto an item, the warmth should adjust according to the table in the Game section above (not by -1); the item should also disappear from the maze.
Part 6Making a Robust and High Quality Game
Back in Task 4, you worked out a set of scenarios that needed to be tested about the game. Implement the tests needed to carry out your plan in a combination of where and/or check blocks.
We are not telling you exactly which functions to test to satisfy your testing plan. We want to see how you put your testing plan into action. Decide where tests are needed and how you want to write them.
As part of making a robust and quality game, you should think about which constraints are needed and where they should be checked. Again, we're not telling you what to do here. We want to see what you come up with.
Part 7Reflecting on Your Design
Answer these questions in your worksheet:
- Look back at your design notes from Task 2. Did your representation hold up? What do you feel worked well (or not!) about your design?
- The maze exists in three forms in this assignment: the spreadsheet, the list of lists of strings, and your own data. Why do we have three forms? What is each good for?
- Describe one mistake or misunderstanding you worked through during this assignment.
- State one question you still have about writing quality programs based on what you experienced on this assignment.
- How did you find this assignment overall? (Help us assess this as part of our experimental course) What parts were interesting and worth doing, what was frustrating, etc.
Grading
At a high level, grading will look at:
- Whether your program lets someone play the game to one of the three levels of functionality listed below
- Whether your code is well organized and has good doc strings
- Whether you have a good testing plan and implemented it through your testing
- Whether your tests and constraints give someone confidence that your code will work well
- How well you can explain how your work meets these above criteria (during code review)
There will not be an autograder on this assignment (because we are letting you all do your own designs with your own data structures).
Instead, we will (a) play your games ourselves on game boards of our own design, and (b) ask AI agents to do an initial assessment of your work prior to your code review. The agents will not determine your grades, but they will help us flag things to discuss during your code review.
Functionality Levels
You don't have to complete all of the game features to pass the project. You will pass if you have a well-tested and well-designed solution with one of the feature sets described below:
- Minimum functionality: the kid moves one cell per key press, can't walk through snow, and the game ends at the school.
- Mid-level functionality: the above, plus items are drawn, warmth drops by one per step and shows in the bar, and the game ends when warmth runs out.
- Full functionality: the above, plus coats, scarves, and flip-flops work as described and disappear after use.
Handin
Hand in this file:
maze-game.arr
Submit to Gradescope. You may submit as many times as you like before the deadline; we grade the last submission.
Comments or concerns?
If you have comments or concerns, submit them on the anonymous feedback form. Sign in with your Brown Google account to open it; your email address is not recorded.