CIT 591 Assignment 8: Wator Applet
Fall 2003, David Matuszek

Purposes of this assignment:

General idea of the assignment:

"Wator" (a deliberate misspelling of "water") is a simple predator-prey simulation. The earliest version of this program may have been written by Robert Martin, but there have been many versions since.

In this version of the simulation, there is an ocean containing big fish, little fish, and algae. Fish can move, eat, and reproduce; if they don't get enough to eat, they can starve to death. Algae just grows. Nothing dies of old age. The Applet will display the "ocean" and some statistics about the contents of the ocean.

There will be a very strict distinction between the Model, which does the actual simulation, and the GUI, which will tell the simulation what to do (Controller) and will display the results of the simulation (View).

Details 1: The Model

The ocean will be represented by a two-dimensional array. Each location of the array may or may not contain algae, and may or may not contain a fish. A location may contain both algae and a fish, but no location can contain more than one fish.

This simulation will use the following parameters:

The interface to the model should be as follows:

public Ocean(int rows, int columns)
This constructor for an Ocean will specify the number of rows and columns in the array. It will construct an "empty" Ocean.

public boolean setNumberOfBigFish(int number)
Set the number of big fish in the ocean to the given value. This is most simply done by removing all big fish from the ocean, then creating and putting in the required number. The method returns true if successful, false if unsuccessful (because there are not enough free locations in the ocean).
public boolean setNumberOfLittleFish(int number)
Set the number of little fish in the ocean to the given value. This is most simply done by removing all little fish from the ocean, then creating and putting in the required number. The method returns true if successful, false if unsuccessful (because there are not enough free locations in the ocean).
public boolean setNumberOfAlgae(int number)
Set the number of algae in the ocean to the given value. This is most simply done by removing all algae from the ocean, then creating and putting in the required number. The method returns true if successful, false if unsuccessful (because there are not enough locations in the ocean).

public int getNumberOfBigFish()
Returns the current number of big fish.
public int getNumberOfLittleFish()
Returns the current number of big fish.
public int getNumberOfAlgae()
Returns the current number of locations containing algae.

public void setBigFishGestationPeriod(int steps)
Sets the number of turns between the times that a big fish can reproduce. For example, if the period is 8, then the fish can reproduce once every eight turns.
public void setLittleFishGestationPeriod(int steps)
Sets the number of turns between the times that a little fish can reproduce.
public void setAlgaeGrowthProbability(double probability)
Sets the probability that an alga will try to extend to an adjacent location.

void setBigFishStarvationPeriod(int steps)
Set the number of turns a big fish can survive without eating.
public void setLittleFishStarvationPeriod(int steps)
Sets the number of turns a little fish can survive without eating.

public void step()
Executes one step in the simulation. See below for details on what happens during a step.

public boolean containsBigFish(int row, int column)
Returns true if the given location of the array contains a big fish, and false otherwise.
public boolean containsLittleFish(int row, int column)
Returns true if the given location of the array contains a little fish, and false otherwise.
public boolean containsAlgae(int row, int column)
Returns true if the given location of the array contains algae, and false otherwise.
 

When fish are created and placed in the ocean, they should vary a bit in how hungry they are and how soon they can reproduce. As a rough guide, no fish should be created on the verge of starvation--maybe they can range from "full" to "half empty."

Values for fish gestation and starvation and for algae growth should be given reasonable default values, so that there is no requirement to call the associated setter values.

The Ocean class will be the only one used by the View and Controller. If a method seems to belong someplace other than in the Ocean class--for example, if you have a BigFish class and you feel that the setBigFishStarvationPeriod(int) should be a static method in that class rather than an instance method in Ocean--then you should delegate the method:

class Ocean {
    ...
    public void setBigFishStarvationPeriod(int number) {
        BigFish.setStarvationPeriod(number);
    }
...

The simulation progresses in a series of "steps." At each step, each fish will

At each step, each alga will:

Note especially that this Model does no input or output of any kind; all communication with the "outside world" is through method parameters and return values. You may, of course, include methods for debug printing, but these should be inactive when the program is delivered.

Details 2: The View

The View displays, as a rectangular grid, the ocean. Empty locations should have an aqua background; locations containing algae should have a green background. Big fish and little fish should be clearly distinguishable by both size and color (for example, little fish blue, big fish red or black).

In addition to the visual display, the current number of big fish, little fish, and algae should be displayed as numbers (with labels). The current step number should also be displayed.

The View should extend Canvas, and should be updated (via its public void repaint() method) after each turn.

Details 3: The Controller

The simulation is either running, or it is not. When the program starts, the simulation is not running. The Controller GUI has Start and Stop buttons to control whether the simulation is running.

The Controller contains "sliders" (scrollbars) to set the number of big fish, little fish, algae, the big fish and little fish gestation and starvation periods, and the probability of algae growth. When the simulation is running, these sliders are disabled. When the simulation is not running, moving the slider has an immediate and visible effect on the View.

The Controller has an additional "speed" scrollbar to control how fast the simulation runs. I suggest a speed range from roughly one turn every three seconds to 5 turns per second (but you can adjust this to suit yourself).

At each turn, the Controller should tell the Model to take one step, then it should tell the View to display the result. (Next week I will discuss a better way to handle the interaction between classes, so this part is temporary.)

Details 4: Classes

One member of the team should tackle the simulation proper, which is done by a class named Ocean. The person programming Ocean may, of course, use any number of additional classes--for example, to represent the fish. The other team member should write the view and controller classes, giving them some appropriate names. As usual, the two team members should work together as much as possible. However, this time you will get individual grades. The two parts of the program (GUI and Model) are of approximately equal difficulty.

I have tried to be very specific about the Ocean interface, which is to implemented by one team member and used by the other. This is because classes should be as independent of one another as possible, communicating only through their defined interfaces. You may not make any changes in the way that I have defined the Controller and View to communicate with the Model. (If my requirements are flawed--always a possibility--tell me about the problem, and I will correct the interface requirements for everyone.) Although I would like for you to work with a partner as much as possible, your individual contribution can (and will) be tested with someone else's code.

Due dates and all that:

Programs will be due by midnight, Monday, November 24. The next assignment may be given out before this one is due, so that there will be some overlap.

The academic honesty requirements for this program will be somewhat unusual. If you are writing the GUI half, you may work with anyone doing the Model half, but not with anyone else who is doing the GUI. If you are writing the Model half, you may work with anyone doing the GUI half, but not with anyone else who is doing the Model half.

Please do not give your source code to anyone. (Your partners are welcome to see your source code, but don't give away copies.) You can give your .class files to your partners--that's all they need in order to use your half of the assignment to make a working program.

Please turn in, via Blackboard, a zip file containing all your source code (.java files). Use the @author tag in the javadoc comments for each class to provide your name. In addition, in the javadoc comments for your ocean or controller class (but not using an @author tag), please mention the names of your partner or partners.