Project: Flingball (Phase 1)
- Team contract due
- Mon Nov 6, 10pm
- Warmup due
- Wed Nov 8, 11am (meeting) 10pm (commit)
- Specs due
- Mon Nov 13, 10pm
- Project deadline
- Fri Nov 17, 10pm
- Reflection deadline
- Sun Nov 19, 10pm
This semester’s group project is a pinball construction kit called Flingball. The original pinball is an arcade game in which the object is to keep a ball moving around in the game, without falling off the bottom of the playing area. The board has various bumpers on it that deflect the ball, and the player controls a set of flippers that can bat at the ball as it falls.
One possible implementation of Flingball. Your implementation will look different.
Flingball has several advantages over a traditional pinball machine. First, multiple people can play it over a network, connected with each other through a server. Each player has their own pinball board, but balls can leave one player’s board and enter another player’s board, running on a different computer. Second, the board layout is configurable by file, so that pinball boards may form complicated “Rube Goldberg” contraptions that are intended to be watched rather than played.
The project will be divided into two phases.
- In phase 1, you will build a version of the game that loads a board from a file and bounces balls around, but without flippers or user interaction.
- In phase 2, you will add keyboard control of the game, plus a client-server component that passes balls between boards over the network, so that multiple people can play Flingball with each other.
In Phase 1 of this project, you will practice working in a small group, using the software engineering techniques we have learned so far this semester: version control, specifications, unit tests, immutable data, abstract data types, and so on. You will also get more practice with grammars and parsers.
On this project, you have complete design freedom to choose the packages, interfaces, classes, and method signatures you use in your code.
Choose them wisely.
You will be expected to use specs, tests, abstraction functions, rep invariants, safety arguments,
checkRep and other assertions.
The specification in this handout constrains what your solution must do, but you will have many design questions that are not answered in this handout. You are free to come up with your own answers to these questions – just be reasonable, consistent, safe from bugs, easy to understand, and ready for change. You can always ask your TA mentor or on Piazza for advice, but there is unlikely to be a single hard-and-fast answer.
On this project, Didit will run only your own tests. As always, correctness is your responsibility, and you must rely on your own careful specification, testing, and implementation to achieve it.
Your team’s repository
To get started, (note: only available after the project announcement in class)
- One member of your team should ask Didit to create a remote
projects/fb1repository, which will create a single repository shared by all members of your team.
Then all team members will be able to clone the repo from Athena using Git:
git clone ssh://email@example.com/mit/6.031/git/fa17/projects/fb1/username1-username2-username3.git fb1
List usernames in alphabetical order.
During the project, class meetings will be partly or completely replaced by team work time. Your team is expected to meet and work together during these times.
Your team will be assigned a TA mentor who will help you with your design and help you stay on track as you implement it. You are required to check in with your TA during every team work time class. At this check-in, each team member should describe:
- what they have accomplished since the last check-in
- what they plan to accomplish by the next check-in
- what, if anything, is blocking their progress
Use the check-in to review how each person’s plans fit together and decide how to resolve blocking problems.
Other than reflections at the end of the project, all parts of the project should be committed to the repository you share. Each commit to the repository should have a useful commit message that describes what you changed.
Use the code review skills you’ve practiced on Caesar to review one another’s code during the project. Caesar won’t have your project code loaded into it, however, so you can use in-person discussion or email for these reviews.
You are also strongly encouraged to try pair programming, where two people collaborate on a single computer. Pair programming is a skill that requires practice. Be patient: expect that pairing will mean you write code more slowly, because it’s like code review in real time, but the results are more correct, more clear, and more changeable. You can find plenty of advice on the Internet for how to structure your pairing.
When multiple people contribute to a commit, mention them in the commit message. Your TA will be reviewing the Git log to see individual contributions.
Pull before you start working, commit and push frequently, and don’t break the build!
Team contract. Before you begin, write and agree to a team contract.
Understand the problem. Read the project specification carefully.
Warmup. There is a warmup exercise that your group needs to do, explained below. It will help you learn how to use the physics engine we provide. You don’t have to use our provided physics engine, but you do have to do this warmup exercise with it before deciding to go your own way.
Design. You will need to create abstract datatypes for various parts of your system: gadgets, balls, boards, and simulator. You will also need to write a grammar for parsing board files, and use it to construct boards with gadgets.
Your software design is perhaps the most important part of the project: a good design will make it simpler to implement and debug your system. Remember to write clear specifications for classes and methods; write data type definitions for your expression data types; define abstraction functions and rep invariants, and write
checkRep; and document safety from rep exposure.
Test. You should write JUnit tests for the individual components of your system. Your test cases should be developed in a principled way, partitioning the spaces of inputs and outputs, and your testing strategy should be documented as we’ve been doing all along.
Implement. Write implementation code so that your tests pass. Iterate on the design and tests as needed to make the system work.
Reflection. Individually, you will write a brief commentary saying what you learned from this project experience, answering the reflection questions. Your reflection may not exceed 300 words, and should be submitted to the reflection form.
Dividing the work
Every team member must not only make a substantial contribution to the project, but every team member must make a concrete contribution to every major component of the project.
For example, you may not assign one team member who is solely responsible for the parser.
Contributions include writing specifications, writing testing strategy, writing tests, prototyping, writing internal docs, writing implementation code, fixing bugs, and giving code review feedback. Contributions you work on as a pair or a whole team are great, as long as everyone is involved. Tasks like running meetings, taking notes, and tracking bugs are important, but don’t count as contributions under this requirement.
You must also divide the work such that every team member makes several different kinds of contributions.
For example, you may not assign one team member who is solely responsible for writing tests.
Here is one suggestion for how to break down the work for a 3-person group. Fill in the cells of this grid so that it is a Latin square, i.e. no person is mentioned more than once in each row or column:
Didit will compile your project and run your tests every time you push.
The automated testing page describes how Didit finds your tests, what tests can and cannot do, and how to exclude tests from execution.
You are not required to run any of your tests on Didit, but your project must compile and have a green build on Didit in order to be graded. If it doesn’t build on Didit, your TA won’t be able to build it either.
The project specification describes how the Flingball system must work for this phase of the project.
Physics. The starting code includes a library of physics methods for calculating the dynamics of elastic collisions. Documentation for the physics package is found online. Its key features are:
- immutable abstract data types such as
Physicsclass that contains methods to model the physics of elastic collisions between balls and other circles and line segments.
A jar file for the physics package is provided in your starting repository. Source code for the physics package can be found inside the jar file. You can look at it by browsing into the jar file in Eclipse. You are welcome to use or not use this code as you please, and to modify it to meet your needs. While this source is provided in the event that you wish to examine or modify it, we generally discourage you from modifying it. Spend your energy on other parts of the project.
Drawing and animation. Example code for doing animated drawing in Java can be found in Smile.java.
The starting code also includes the jar for
ParserLib, which must be used for parsing the file format.
Documentation for ParserLib is found online.
In order to get familiar with the physics package and get the hang of the physical simulation part of the project, you should write a small program that simulates a single ball bouncing around an empty 20L x 20L board. The ball should have a slow fixed speed (about 5L/sec) and reflect off each wall that it collides with. Don’t simulate friction or gravity. As the ball bounces around, the position of the ball should be printed periodically to the console, at 10-20 frames per second.
main() method of your warmup program should be in the class
Main in package
warmup, i.e. in the file
src/warmup/Main.java in your repo. You can create other classes in the
warmup package that help make it work, like
Ball, or you can implement everything inside
Main. The code in
warmup will not be part of your final project implementation, and you aren’t expected to write specs and tests for your warmup code. This is throwaway practice code for learning about the problem and how to solve it using the physics package.
Deliverables and grading
- Mon Nov 6, 10pm
- Your team contract must be committed to your group repository in a PDF file called
team-contract.pdfin the top level of your repo.
- Wed Nov 8, 11am
- Milestone meeting: you will have a meeting with your group’s TA mentor, at which you must demonstrate the deliverables described under warmup. You will demo the code and discuss your work at the meeting. Have a laptop with the program ready to run. Then commit your warmup code to your group’s repository by that night at 10pm.
- Mon Nov 13, 10pm
- You should have committed (1) a grammar for the complete board file format, (2) specs for all your classes and methods, and (3) some progress on testing and implementation.
- Fri Nov 17, 10pm
- Project deadline. Your specifications, tests, and implementation should be complete and committed to your group’s repository.
- Sun Nov 19, 10pm
- Reflection deadline. Individually, you should write a brief reflection and submit it using the reflection form. Your reflection should be at most 300 words of plain text.
Grades will be determined according to the following breakdown:
- Team contract: 5%
- Design: 25%
- Implementation: 40%
- Testing: 25%
- Reflection: 5%
The warmup and specifications deadlines are graded as binary checkoffs. Missing each of these intermediate deadlines will cost 5 points on the overall project grade. The associated milestone meetings also contribute to your design and implementation grades.
Check-ins with your TA mentor are also graded as binary checkoffs, either passed or missed. Missing a check-in costs 1 point on the overall project grade. You should check in with your mentor during class on:
- Mon Nov 6
- Wed Nov 8 (this is the milestone meeting)
- Mon Nov 13
- Wed Nov 15
- Fri Nov 17