CO307 Coursework 2: TheShip
---------------------------

=======================================================================
Aidan, Hilary & Gerard,

Guys.  This is the documentation I will be submitting for this project.
Please let me know FAST (email) if you want to make any contributions
to this document.  In particular, if any of you know what is actually
meant by the 'terms of reference for group members' I would be glad to
find out.

Also could each of you please email me you student ID numbers so they
can be included in this documentation.
=======================================================================


Group Members:
  Eamonn Martin		EFM001
  Aidan Orton		AIO001
  Hilary Woods		HIW001
  Gerard Dolan		GED001


1. Specification

This applet simulates the behaviour of a sailing boat at sea.  The
goal for a user is to sail from the start point (marked with a cross)
to a finish point (marked with a square) as quickly as possible without
incurring disaster.  The boat can sail in any direction up to and
including 45 degrees either side of the direction from which the wind
is currently blowing.  If the boat attempts to sail closer to the wind
than this, it stops, but can still be steered. If the boat sails at
more than 90 degrees to the wind it sails backwards.  If it sails too
close to the edge of the display, it will sink.  The boat is blown
over and sunk if the product of the area of the boat's sails and the
strength of the wind is greater than the product of half the sail area
and half the wind strength. The wind strength can vary from 0 to 40
knots in increments of 1 knot.  The wind direction is randomly changed
automatically.  The speed of the boat is proportional to the strength
of the wind, and varies between 0 and 10 knots in increments of 1 knot.
The user of the program can change the direction in which the boat is
sailing by an increment of one degree left or right by clicking on
appropriate buttons using a mouse.  S/he can also change the sail area
of the boat, which may be 0, 5, 10, 15 or 20 square metres. The boat
keeps a log, (in memory) which is a record of every change of speed
and/or direction steered and the times at which these occurred, since
the voyage began.  The user can obtain a summary of the log at any
time by clicking on the appropriate button.  The summary consists of
the total distance covered by the boat, the straight line distance
over the ground which it has covered, and the total time for the
voyage so far.  The simulation is animated in time increments of
100ms, after each of which the state data is automatically updated.

The boat is represented by a small red arrow pointing in the direction
the that the boat is currently sailing.  The direction of the wind is
indicated by a larger blue arrow in the bottom-right corner.  Next to
this are three bars which indicate the sail area, the speed of the boat
and the wind speed.  The output of the 'Show Log' button is displayed
in the status line.


2. Design

This program uses the java.awt and java.applet packages.  It consists
of six classes and one interface, as listed below:

    Ship		Ship state-data and operations
    ShipsLog		The ship's log (a linked-list)
    LogData		Data returned from the ship's log
    Angles		Generic methods for calculations with angles
    TheShip		Event-handlers and Animation implementation
    Animation		Animation interface
    AnimationTimer	Animation thread control


class Ship
This class contains all the state-data for the boat and the wind and
the methods for interacting with that data.  It also contains all the
constants which define the layout of the display.

class ShipsLog
This class is created by the Ship class to log any change in the speed
and/or direction of the boat.  The log is implemented as a linked-list
of ShipsLog objects, with each object containing the time of the change
and the boat's new speed and direction.

class LogData
A data structure used by the Ship class to return a summary of the data
stored in its ShipsLog list to the TheShip class.  The TheShip class
(which extends Applet) uses Applet's showStatus() method to output the
log summary in the browser's status line.

class Angles
Contains several class methods which are used by the Ship class to
perform calculations with angles.  These methods are generic enough
to be placed into a separate class for re-use in other applications.

class TheShip
This class contains the data and code used to initialize the applet.
It also contains the methods for handling events (action, paint) and
methods which implement and control the Animation interface.

interface Animation
This interface defines a single method (animate) which is called by
the AnimationTimer thread and is implemented by TheShip.

class AnimationTimer
This class contains the main program loop which controls the timing
of the animation.  It also contains the methods which start and stop
the execution thread of the applet.


3. Terms of Reference

Hilary Woods...:  Specification
Aiden Orton....:  Design
Eamonn Martin..:  Coding
Gerard Dolan...:  Testing


4. Development Plan

Week 7
Program specification and the scope of the implementation discussed.
Implementation specification to be finalized by week 9.

Week 8
Initial prototypes demonstrated.  Discussed implementation as an applet
or as a complete application (decided on applet).  Terms of reference
established for each group member.

Week 9
Implementation specification finalized.  Intermediate versions of the
program analyzed and modified by the group.

Week 10
The need to modify the ship's log to conform to the formal specification
was identified (store speed/direction, not x/y coordinates).

Week 11
Finishing touches added and final system agreed.


5. User Instructions

When the applet initially starts, the ship's sail is down and so the
ship will not move.  The timer begins counting immediately, however,
and the wind speed and direction begin changing automatically.

Each click on the 'Sail Up' button raises the sail by 5 square metres
and each click on the 'Sail Down' button lowers the sail by 5 metres.
The current sail area is indicated by a horizontal bar marked 'Sail'.

A click on the 'Left' or 'Right' button turns the ship left or right
by one degree.  The ship stops moving if it goes above 45 degrees to
the wind and sails backwards if it goes above 90 degrees.

Clicking the 'Show Log' button at any time causes a summary of the
data in the ship's log to be displayed in the browser's status line.

The animation stops if the boat sinks, arrives at the target area or
sails out of the display area.  The animation can be restarted by
reloading the applet.