In this project, you will implement a real-time simulation of cloth using a mass and spring based system. You will build the data structures to discretely represent the cloth, define and apply physical constraints on them, and apply numerical integration to simulate the way cloth moves over time. Finally, you will implement collisions with other objects as well as self-collisions to prevent cloth clipping.


Component Deadline
Checkpoint Quiz 04/04/2023
Assignment 4 04/11/2023

Project 4 is due Tuesday 04/11/2023, 11:59PM. You have a total of 6 slip days to use on assignments throughout the entire semester, but you do not have slip days for checkpoint quizzes. Assignments submitted after 11:59PM are considered as a full day late. There is no late minutes or late hours. After you have used all 6 slip days, you will lose 10% for each day you submit an assignment late.

Your final assignment submission must include both your final code and final write-up. Please consult this article on how to submit assignment for CS184.


You can optionally work with a partner on this project. If you work with a partner, both of you should join the same team on Github Classroom. You should also produce 1 writeup and 1 gradescope submission with the partner added on.

Checkpoint Quiz

The checkpoint quiz can be found on Gradescope and is intended to help you get started on Project 4. It is due Tuesday 04/04, 11:59PM PST. If you are working with a partner, both partners must submit the quiz!

The content necessary for answering all questions can be found on the project spec or in lecture material. You will receive 5 "buffer points" for completing the quiz only if you answer at least 4 out of 7 questions correctly. These 5 buffer points will be added to your Project 4 grade, capped at increasing your score to 100. For example, if you earned 96 points on the base project and 2 points of extra credit, the 5 buffer points will bring your score up to 100, and the extra credit will bring your total score to 102.

You may change your answers after submitting, up until the deadline. No slip days may be used on checkpoint quizzes.

Project Parties

We will have 5 project parties for this project. Keep an eye on Ed/the website calendar in case any of these need to change:

  • Friday (3/24), 1-3pm: Berkeley Way West (BWW) Room 1204 & 1213 (shared with Proj 3-2 due to overlap)
  • Wednesday (4/5), 7-9pm: Cory-400 Hughes Room
  • Friday (4/7), 1-3pm: Berkeley Way West (BWW) Room 1204 & 1213
  • Monday (4/10), 4:30-6:30pm: Cory-299
  • Tuesday (4/11), 5-7pm: Cory-293

Project structure

The project has 5 parts worth a total of 100 possible points. Some require only a few lines of code, while others are more substantial.

You'll also want to check out the website writeup and deliverables.

Getting started

You can clone the assignment from your private repo using the command


Building and running the program

As before, refer to this how to build cs184 projects document to build your project.

After you have built the program, you will have an executable file clothsim that takes in zero or one argument. Running the program with zero arguments will load up the default scene. Otherwise, to load a specific scene, run the program as follows:

./clothsim -f ../scene/<my_scene>.json

You will also need to use the -o and -a flags for the write-up, which control the resolution of the rendered spheres. -o <INT> controls the vertical resolution, and -a <INT> controls the horizontal resolution. For example, this will render a particularly high-quality sphere:

./clothsim -f ../scene/sphere.json -o 128 -a 128

Getting acquainted with the starter code

Before you start, here is some basic information on the structure of the starter code.

  • cloth.cpp/h: The cloth representation, as well as methods that directly change the cloth during the simulation
  • clothSimulator.cpp/h: The primary program that wraps around the cloth and its constituents and runs the simulation and GUI
  • spring.h: A struct definition for a simple spring in our mass-spring system that represents a connection between two point masses
  • pointMass.h: A struct definition for a single point mass that discretizes the cloth and is affected by forces (e.g. spring forces, gravity) in the system
  • collision/: Directory containing struct definitions for static primitive objects, such as sphere.cpp/h and plane.cpp/h
  • scene/: Directory containing various scenes saved in JSON format

In this project, you will write code in cloth.cpp, collision/sphere.cpp, and collision/plane.cpp.

Using the GUI

Besides the actual graphical user interface that you can work with using your mouse to tweak cloth parameters and dynamically change external forces, there are several keyboard commands that you might find useful.

Command Key
Pause simulation P
(while paused) Go forward 1 timestep N
Restart simulation R
End simulation ESC
Reset camera to default position SPACE
Rotate camera (click and drag, or right click)
Pan camera (hold control + click and drag, or right click)