Whack-A-Mole

The CS2 Second Project

Due Dates

Part 1
Sunday, April 14, 2019 by 11:59 PM
Part 2
Sunday, April 28, 2019 by 11:59 PM
Part 3 (survey)
Monday, April 29, 2019 by 11:59 PM

Overview

You will be designing and implementing a networked, multiplayer version of the arcade game Whack-A-Mole. This activity will build on your recent experiences in multi-threading, networking, and graphical user interfaces.

It is intended that you work on this project in teams of two. Students are not allowed to opt out of having a teammate simply due to preferring to work alone. Teamwork is part of the learning experience for this course.

Background

The game you will build is strongly based on the arcade game Whac-A-Mole, (™Bob's Space Racers). It is popular in amusement arcades, but there are home and Internet versions as well. There are many descriptions of the game online. Here is a video of a good player, playing on a standard five-hole board.

Our Rules

The goal of the game is to "whack" (touch the heads of) as many moles as possible. Moles can only be whacked when they have popped up out of their holes. More precisely for this version of the game, the goal is to attain the best score among all the players in a game. A player's score increases when a popped-up mole is whacked, and one's score slightly decreases when an attempt is made to whack a mole when it is down. (Scoring details are given below.)

This version of the game is multi-player. All players see the same pattern and timings of mole pop-ups and pop-downs. This includes the fact that, when whacked on one player's board, a mole pops down on all players' boards.

Provided Design

Your implementation of the game will use a JavaFX user interface for players. It will be be networked, with each player running its own Java process, and a server also running in a separate process. The server will open its ServerSocket on a well-known port, meaning that any client would know this port so that it can connect to the server. As the term "networked" implies, all such processes can be running on different computers. We will call the software these processes run components of the project

All implementations must observe the same protocol, specified in the file WAMProtocol.java. This means that a player component written by one team will work fine with a server written by another team. (Any enhancements you choose to do beyond the specifications herein must not change this rule.) Here are some specific rules to which your design must adhere.

Protocol

Being a networked system, there are components that communicate with each other. The sequence diagram below represents an example scenario for the communication. The boxes at the top represent the components -- instances of Java programs that can run on separate processors. The stick figures are actors. In the UML, actors represent anything outside the system being designed. In our case the actors are the users that start up the server and the "client player" programs. The arrows represent messages between components, and time increases as you move down the diagram. (The start and whack messages are not real messages; instead they represent the components being started up and the users interacting with the user interfaces.)

Getting a Teammate

The instructors will be telling how teams will be assigned. You will be told of a GitHub Classroom repository you and your teammate will be able to use. Do take advantage of Git by doing frequent pushes to the same repository. That way both team members can easily stay up-to-date. GitHub Classroom team setup instructions are provided here. Also see the document JetBrains+GIT for valuable insights and information about keeping your repository uncorrupted in the face of multiple developers.

All teams must be finalized (including instructor approval) by 5:00 PM on Friday April 5th.

Only one person from each team submits each deliverable for the project to the dropbox. Of course, equal contributions from the members of the team are expected. It does not matter who makes the final push to the Git repository. If both team members submit to the dropbox, it just makes things confusing for grading. It may be that we arbitrarily decide which one to grade.

On Required and Optional Features

Your programs must implement the functionality described in this document. You may add additional features, but your grade will solely be based on implementing the functionality in this document. Any additional features must not interfere with required functionality.

Invocation Commands

The server will be compiled with the JavaFX 11 libraries specified in the setup instructions. The command line arguments, besides the VM options required for JavaFX, are as follows.

game-port#  #rows  #columns  #players  game-duration-seconds

For example the following arguments represent a game with well-known port 20185, 3 rows by 4 columns, and 2 players that will run for 30 seconds, once the final player connects.

    20185 3 4 2 30

The client player programs will be invoked with the server's host name or address, followed by the server's game port.

The command line arguments for both server and client must be checked. If there is a problem, the program should terminate after printing a message on standard error but before the application window appears, when appropriate.

Mole Up-Down Timing

We are not specifying how long the moles stay up or down, or what kind of time distribution to use. But there are three rules.

  1. The mole timing must have a random element to it.
  2. The chosen timing cannot make the game too hard to play, for testing.
  3. Extra command line arguments cannot be required.

We have a reference implementation in which the up time is uniformly distributed between 3 and 5 seconds, and the down time is uniformly distributed between 2 and 10 seconds. This makes for a fairly easy game in which to accumulate points, depending on the board size.

Code Package Hierarchy

To ease in grading, use the following package structure and main program file names.

common
for Java files used by both the server and clients (players)
server
for Java files used only in building the server
Call the main program WAMServer.java.
client.gui
for Java files used only in building the player/client program
Call the main program WAMGUI.
(The subpackage gui is placed here in case you want to build an alternate plain text user interface. But it is not a requirement for the project.)

Feel free to make more sub-packages below those.

Look And Feel

How you represent the game visually is up to you. However, remember two things.

  1. Whacking must be done by doing a mouse click on a part of the displayed game that clearly looks like a mole or mole hole.
  2. The difference between a popped-up mole and a down (hiding) mole has to be obvious.

You are strongly encouraged to design and implement a bare minimum GUI so that you can play and test the game. If you have time at the end, after everything else is working, feel free to spend more time on making your GUI beautiful.

Adding debug messages to the consoles of both the client and server is encouraged for your sake. It will not influence your grade.

Help

Your Team's Port Number

Here are some suggestions on how to choose a well-known port for your version of the game server that does not conflict with others, when running on the same computer. This will happen if one or more teams choose to run on one of the department's larger machines like glados.cs.rit.edu.

If you are having trouble, for example if the server cannot bind with the port, try running on a different machine to see if that helps.

Sample Game Server

A server is being prepared against which you can test your client code, especially when you are working on Part 1. (See Submission.) It will normally be running on dione.cs.rit.edu, on port 20185. It supports only single-player games. However, keep an eye on the discussion posts in myCourses to find out the status of the server.

Provided Code

The protocol messages are provided in an interface WAMProtocol, available here. Although it is an interface, there is nothing to implement. The interface contains only static string constants for the different message types. They are documented with how they should be used. (Again, see the sequence diagram for a sample scenario.) This is the only file provided in the starter repository mentioned in the team setup section above.

To use the interface, put it in a package called common, and put this line in the code files that need it.

		import static common.WAMProtocol.*;

Two other classes you may find useful are the listed below. You may add them if you decide to use them. They belong in the package edu.rit.cs.

Observer.java
The class used in lecture to represent the observer of subjects in the Observer design pattern. It was specifically used in graphical user interfaces as a way for the view (the graphics) to watch for changes in the model. Even if you decide to use it, you still need to provide the design for the subject (observable) part of the design pattern.
ConsoleApplication.java
You will likely not want to use this. However one approach to developing a project like this is to build a plain-text user interface (PTUI) first, in order to validate your server implementation. The ConsoleApplication class was designed to look like the JavaFX Application class, so that less code would need to be discarded once you are ready to build your GUI.

Submission

All your source code must list all team members as authors, with the major contributor first. You have two submission deadlines.

By each due date, submit a zipped file (not 7zip, not tar, not tgz, not rar) to the Dropbox in myCourses. The zip file must contain exactly the src directory and all of its contents.

Also push your project to GitHub by each due date.

Part 1 Submission

By the first due date, only one member of each team must submit client code that does the following.

  1. Start up a single client.
  2. Connect client to server.
  3. Draw board.
  4. Show mole pop-up and pop-down activity.
  5. (SCORE and the set of win/lose messages can be ignored.)

The client code will not need to respond to user events.

Name your zipped project's src directory contents project2_part1.zip.

Part 2 Submission

The full project as defined in this document is due by the second due date. Only one team member submits the file to the dropbox. This includes the rest of the client functionality.

  1. Send WHACK messages to the server.
  2. Display score.
  3. An indication of who won the game. (In part 1, with a single player, you always win!)

Name your zipped project's src directory contents project2_part2.zip.

Part 3 Survey

By 24 hours past the due date, fill out the survey that will be announced a few days earlier.

Grading

Part 1

35 points

Part 2

60 points

Teams can recover up to 20 of the lost points on Part 1 if things work when Part 2 is submitted.

Note that your code must conform to the protocol specified in this document. Again, recall that you can test with the reference server to verify this.

Points may be deducted for poor code style.

Survey

5 points

Grade Adjustments

Failing to follow rules regarding team setup
Up to -10%
Unequal contributions from team members1
Range ±15%

1. We will be checking github commits to determine individual contributions.