Deadlines

Warning: There are 3 deadlines for this project, and some deadlines require you to submit multiple deliverables. Please double-check that you submitted everything!

Assignment	Tasks	Deliverable	Points	Due Date
Project 5A	- Partnerships - Setup - Design Document	Partnership formation	10	Friday, Apr 10 11:59pm PT
		Design Document	50	Wed, Apr 15 11:59pm PT
Project 5B	- World Generation	World Screenshots on Gradescope	40	Tues, Apr 21 11:59pm PT
Project 5C	- Task 1: Main Menu - Task 2: Interactivity - Task 3: HUD - Task 4: Saving and Loading - Task 5: Pathfinding - Task 6: Ambition Features	Code on Gradescope	150	Tues, Apr 28 11:59pm PT
		Live Checkoff with TA (Checkoffs will happen 4/27 – 5/01)	150

To request extensions on Project 5, both partners need to submit separate extension requests on Beacon.

Project 5A: BYOW (Partnerships and Design)

Welcome and Overview

In this project, you will create an engine for generating explorable worlds. This is a large design project that will require you and one partner to work through every stage of development from ideation to presentation.

In accordance with this, the grading of this project will be different from other projects. Since there is no notion of “the correct answer” when it comes to world design and implementation, you will be assessed much like a performance review you might receive at an internship or job. While this means you will be graded slightly subjectively, we promise to be pretty nice bosses and will respect you as any boss should respect their hardworking employees. You will have the opportunity to dispute if the grading scheme feels unfair.

This project is about software engineering, and will achieve several goals that come with large design projects

1. Emulating a real product development cycle. This comes from handling a larger pieces of code with little starter code
2. Recognize and mitigate code complexity. Inevitably, whenever a team builds a large software system, they’ll make some bad design decisions and cut corners, resulting in “technical debt”. Your code becomes complicated to understand and modify, which in the real world translates to software that becomes stale and expensive to maintain. It is very likely that your code will feel sort of hacked together by the end of this project. As you grow as a programmer over the course of your career, arguably the main skill you’ll be building is to avoid such hacks. However, the only way to know and defeat this is to suffer from it.
3. Exploring and experimenting with resources. Know that there are no right and wrong answers, as this is a very open-ended project. In fact, it is not required to use any of the data structures from class, but it will likely make your solution significantly simpler and more efficient. You will likely go through several iterations before settling on your final implementation

Don’t miss the Software Engineering I lecture, in which I’ll go through John Ousterhout’s great book about managing software complexity.

A video playlist (from Spring 2018) discussing tips for working on this project can be found at this link Note: The tour through the skeleton code is a bit out of date, for example, the playWithKeyboard and playWithInputString methods are gone.

Your task for the next few weeks is to design and implement a 2D tile-based world exploration engine. As an example of a much more sophisticated system than you will build, the NES game “Zelda II” is (sometimes) a tile based world exploration engine that happens to be a video game:

The system you build can either use graphical tiles (as shown above), or it can use text based tiles, like the game shown below:

We will provide a tile renderer and a small set of starter tiles for you to use. This will be the same tile renderer you used in Project 0 and 3.

Project Roadmap

1. Implement code to generate random worlds (Project 5B).
2. Add a main menu for the user to start the game from (Project 5C).
3. Add support for saving a game and loading it back (Project 5C).
4. Add several game mechanics/features to your project (Project 5C).

Large Language Model (LLM) Policy

Recall that in the collaboration policy, we say:

“Use of GitHub Copilot / ChatGPT / Claude / etc. If you’re just generating some amount of boilerplate code, that’s ok. However, you should not use such tools to generate non-trivial methods. We are trying to build your fundamental skills, and leaning on an AI is going to cause you trouble in circumstances where you don’t have an AI to help, such as exams. Any AI generated code must be cited and explicitly commented as such. Violation of this citation rule is a serious act of plagiarism. Note that generative AI is designed to output data that looks correct, not output data that is correct. As such, AI-generated code, especially from sources like ChatGPT, is often subtly buggy or completely incorrect.”

Task 0: Partnership Formation

Follow the instructions below to create your group in beacon!

This is due on April 10th at 11:59 PM. If you do not create a partnership by then, you will be randomly assigned, so make sure you get this done!

For policies, tips and general FAQ regarding partnerships, checkout the Partnership Guide for more info.

1. Navigate to Beacon and click on the Groups tab in the top navigation bar. Under Assignment, select Project 5, then enter your partner’s repository ID and click Send Request.

   

   After sending the request, it will appear as pending until your partner responds.

2. Your partner will see an Incoming Group Request by navigating to the same Beacon page, where they can either Accept or Reject the request.

   

3. Once the request is accepted, both partners will be placed in a group and gain access to a shared repository. You should also receive a confirmation email once the group is successfully formed.

   

Task 1: Setup

The setup for this project is different from all other assignments so far. Read this carefully and do not skip any steps!

Follow the instructions below after partnerships have been released to use your group repo. Make sure to provide a screenshot of your group repository to submit to gradescope to show that you have accepted the invite.

You need to accept your Github repo invite within a week of it being sent, or else it will expire, and you will not be able to work on the project.

1. Go to your email associated with your Github account and accept the Github repo invite.

   

2. Screenshot your github repo like below, showing that you have accepted the invite. Here is an example

   

3. Log in to Beacon, and click on the “Groups” tab. You should have a group listed here.

4. Click the “View Repository on GitHub” link.

5. Click “Code” -> “SSH” and copy the link that appears. It should look like this, with *** replaced with some group number:

   git@github.com:Berkeley-CS61B-Student/sp26-proj5-g***.git

   

6. Open a new terminal window in your local computer.

7. Use cd to navigate to your desired location your project. Most students have a folder called cs61b.

   Do not navigate to your personal sp26-s*** repo! You should not be cloning your group repo inside your personal one.

8. In your terminal, clone your repo, replacing the URL with the one you copied earlier:

   git clone git@github.com:Berkeley-CS61B-Student/sp26-proj5-g***.git

9. Navigate into the repo you just cloned:

   cd sp26-proj5-g***

Once you’ve completed the above steps, you should see your new group repo called sp26-proj5-g*** in your local files, and if you open this repo, you’ll see the proj5 skeleton folder. From here, you and your partner can proceed as normal, by adding, committing, pushing, and pulling from this repo as you would otherwise.

Before getting started, please read the Project 5B: World Generation and Project 5C: Gameplay specs. You won’t be able to begin either task without understanding the BYOW spec first!

Task 2: Writing Your TDD

We have provided a template for you to use if you’d like. See the Project 5A: BYOW Design Template, which is also linked in the assignment below.

Check the Technical Design Document tab for a refresher and an example of a design document

As mentioned earlier, design docs are living documents. You (the designer) might not understand the entire project scope while drafting, and that’s fine. Including a section for questions can help track your thoughts for future iterations.

A “Questions” section is useful for collaboration. Your collaborators may want to understand which assumptions you made or questions you had when designing.

Write a TDD for BYOW and submit it to the Project 5A: BYOW Design assignment.

For BYOW, the complexity of your program is not as important.

On the other hand, the data of your program is. What type of data do you expect to save and load?

If you expect to work on this project during office hours, we may ask to see your design document to help understand your approach. As such, please put effort into this assignment! Grasping project requirements in the design phase will help immensely during the later implementation phases.

Design Tips

We’ve included below a few questions for you to consider while brainstorming your design:

General Questions

• Look through the provided code:
  • Notice what’s already built for you. What may be useful for your implementation?
  • Notice what isn’t. What gaps does your implementation need to fill?
• Where do tasks overlap? Are there opportunities to reuse methods across different cases? Think about opportunities for helper methods.
• Can you find groups of data structures and methods that serve a similar, clearly defined purpose? If so, consider moving them to a separate class. Building abstraction barriers may be helpful for managing code complexity.

World Generation

• What are the core components of each world? Does it makes sense to have a separate class for each component?
• How will you ensure that every generated world is valid?
  • Will you decide on a layout first, validate it, then build the world after?
  • Or, will you gradually generate the world, ensuring that only valid components are built as you go?
• Ultimately, each world is a 2D grid of values, each representing a Tile. What data structures would be helpful for tracking the state of the world on top of this grid? Representing specific aspects of your world with data structures may be helpful for building ambition features later.

Interactivity

• Read through the StdDraw library documentation. This library acts as the bridge between your implementation and what is outputted on screen (e.g. the /tileengine implementation uses library methods to draw to the screen).
  • Can you find methods for drawing on the screen, not specifically for tile drawing?
  • Can you find methods for soliticiting user inputs?
• Rendering video is much like a classic film projector, in that by rapidly rendering images, we can create the illusion of motion. Video games are essentially the same, except that user inputs can alter what’s displayed in the next frame. (Read about common paradigms for implementing video games and graphics engines here)
  • Does your implementation clearly separate the steps of collecting, processing, and displaying the result of user inputs?
• Consider that your computer can compute thousands of instructions each second. If your implementation has real-time elements (i.e. timers, slow-motion movement, NPCs moving at user-like speed, etc.), how can you adjust the speed of your event loop to match real-time?

Ambition Features

• Most importantly, which ambition features are you most excited about building?
• For each feature, determine where it fits within your current abstraction barriers:
  • Does it require fundamental changes to the process of generating and representing worlds?
  • Does it alter the process for collecting user input?
  • Does it change the process for rendering the world state?
• Do any features span multiple domains of this project? If so, consider creating separate classes to contain their complexity.
• How could you structure your core project implementation (world generation and interactivity) to make feature integration seamless?

You aren’t bound to the ambition features you choose to write about within your design doc. That said, certain features (especially primary ones) are better aligned with certain implementation choices in the world generation and interactivity tasks. It’s important to think about this early!

Submission

Submit your design document on gradescope: Project 5A: BYOW Design (5 points)

Don’t forget to add your partner to the submission!

The score you receive on Gradescope is your final score for this assignment (assuming you followed the collaboration policy).

While we’re unable to give detailed individual feedback for each TDD, we’ll agregate common mistakes we notice and showcase them (as well as implementation hints…) in assignment section during Week 13 (11/17-11/21). As always, come to office hours if you want specific feedback from 61B staff!

A note on grading, we are looking for thoughtfulness and effort. In other words, you do not have to be correct in your design or your complexity analysis, but we expect you to have put in considerable time into designing your approach. As long as you attempt to describe your approach for the components in the rubric, you’ll receive full credit.

For the TDD, we have provided the rubric we’ll be grading submissions on below for your reference.

1. Data (10%): Describes how the data will be used.
2. Data Structures (40%): Describes what data structures will be used with the data.
3. Algorithms (40%): Describes what algorithms will be used with the data structures and data.
4. Complexity (10%): Describes the expected time and space complexity of the program.

This spec was written by Daniel Wang and Ronnie Beggs as a new assignment in Fall 2025. The provided template was created by Kanav Mittal and Stella Kaval in Spring 2025 and edited by Daniel Wang.