Project 1 - Battleship Game

Minimal Submission Due: Friday, December 16th, 2005

Final Project Due: Sunday, January 29th, 2006

Revision History

  • Dec 8th, 2005: Initial revision released to public.
  • Dec 8th, 2005: Changed sample output section.
  • Dec 9th, 2005: Updated sample output section to show what happens when the "view ships" command is executed after the program is run and ship/s have already been hit. The entire ships should still be displayed as normal, without any missile hits.
  • Dec 9th, 2005: Changed input file format to include the number of ships as the first value in the file. There is now an additional error if the number specified does not match the actual number of ships.
  • Dec 14th, 2005: Added the exact formula used to compute the hit/miss ratio in Figure 2.

    Overview

    In this project, you will be required to write a simple one sided battleship game. Your program will start by generating a new board and randomly placing ships on the board. From there you will have a chance to fire missiles to try to sink the ships. You will also be able to view the board, view the ship placement (cheat mode) and get the game statistics.

    Objectives

    Getting Help

    You may get help from your instructor(s) and the teaching assistants. Anything else is not allowed and is subject to the penalties listed in the DCS Policy on Academic Dishonesty. This includes but is not limited to:

    We certainly do not expect there to be absolutely no communication between the students of this class; we know that people tend to learn very well that way. However, we expect that you will limit your discussion of this project to determining the specification of the problem. If you have any doubt if what you would like to do might violate our rules, please see your lecture instructor for clarification.

    Don't forget that the CS tutoring center is available to you.

    Program Requirements

    Battleship is a popular game played on a board representing a rectangular portion of the sea. It is broken up into a grid of square cells, each one having a unique pair of coordinates. Battleships are placed on the board. Each battleship covers a straight line of two, three, four, or five squares. The opponent does not know where the battleships are; he or she fires missiles into the sea, specifying coordinates, and is only told if it was a hit or a miss. The player who fired the missile uses this information to guess the locations of the battleships. A battleship is sunk when all of its sections have been hit by a missile. The goal is to sink all the battleships.

    Usually it is a two-player game, each one having his/her own board. You will create a one-player game, where the program places battleships on a board and the user is the opponent trying to sink them.

    Your program must be able to create a new board, place the ships randomly or as specified in a file, be able to fire missiles at the user-specified the locations, and keep track of the game's state. The ships cannot be placed off the board or on top of each other. Game statistics must be kept throughout the game, keeping track of the number of hits and misses, the total number of missiles fired, and the number of ships sunk.

    Command Line

    The game shall be started as follows:

    java Battleship N [filename]

    The value N represents the dimensions of the board. Since a board is always square, there are N columns and N rows. (For a board of size N, the legal row and column coordinates are 0 to N-1.)

    If the optional argument is absent, ships will be placed randomly on the board in the following quantities:

    Input Format

    If the optional filename argument is present, it is the name of a file whose first line contains the number of ships, followed by one line each for each ship position, in the following format:

    	startRow startColumn direction length
    

    startRow and startRow are non-negative integers. direction is one of N, E, S, W, meaning North (towards decreasing row numbers), East (towards increasing column numbers), South (towards increasing row numbers), and West (towards decreasing column numbers), respectively. length is the number of cells that the ship covers. It is an integer between 2 and 5, inclusive.

    Example

    If a board size of 10 has been specified and the input file input-2.1 contains the following:

    2
    2 2 E 3
     3  4  S  5
    

    then the initial board setup would be as follows:

         0  1  2  3  4  5  6  7  8  9
      0  -  -  -  -  -  -  -  -  -  -
      1  -  -  -  -  -  -  -  -  -  -
      2  -  -  C  C  C  -  -  -  -  -
      3  -  -  -  -  A  -  -  -  -  -
      4  -  -  -  -  A  -  -  -  -  -
      5  -  -  -  -  A  -  -  -  -  -
      6  -  -  -  -  A  -  -  -  -  -
      7  -  -  -  -  A  -  -  -  -  -
      8  -  -  -  -  -  -  -  -  -  -
      9  -  -  -  -  -  -  -  -  -  -
    

    (More on output format later.)

    If any errors occur in the data used by the game upon startup, an error message must be printed on standard error and the program halted. Here is a table of possible error situations and the messages displayed as a consequence.

    Fig. 1: Error Situations and Messages
    *required for minimum submission

    error

    message to be displayed (all terminate with a new line)

    Illegal number of arguments* Usage: java Battleship N [config-file]
    1st command line argument is not an integer* Usage: java Battleship N [config-file]
    1st command line argument < 5* Board must be at least 5 by 5.
    1st command line argument > 100* Board must be at most 100 by 100.
    File named by second argument cannot be opened. Cannot open file filename.
    Incorrect number of ships specified in file (this includes zero ships). Incorrect number of ships in file filename.
    Length of ship is outside the range [2,5]. Illegal ship size in file filename.
    Specifications of ships cause them to overlap. Overlapping or out-of-bounds ships in file filename.
    Specifications of ships extend beyond the boundaries of the board. Overlapping or out-of-bounds ships in file filename.
    Improperly formatted data in the config-file (includes premature end of file) File filename has corrupted contents.

    The first thing that happens after the program is started is that the board layout is displayed as if the user had typed "view board". The user will then be prompted for a command by displaying "> " on a new line.

    The commands are as follows:

    Fig. 2: User Command Input Semantics
    Command Description
    view arg If arg is board,
    Print out the placement of the missiles on the board. Each previous fired missile destination must be marked with either an X or an O signifying a hit or a miss, respectively. This printout must not show the placement of the ships.

    If arg is ships,
    Print out the placement of the ships on the board. Each ship must be represented by a letter corresponding the the size of this ship. A is an aircraft carrier of 5 cells. B is a battleship of size 4. C is a cruiser of size 3. D is a destroyer of size 2.

    If any other string is provided for arg, the user will get the error message "Can only view board or ships." on standard output.

    For the precise format of the output, see the Output Format section later in this document. Note that you must allow for 2-digit row and column numbers, and the column numbers must be separated by a single space.

    fire row col Fire a missile at the square at the given row and column. Both coordinates will be given as integers. The status of the missile must be changed depending on if it is a hit or a miss at the current spot on the board.
    If there is a missile already there, the user will get the error message
    "Coordinates previously fired upon." on standard output.
    If the coordinates are out of range, the user will get the error message
    "Illegal coordinates." on standard output.
    If the missile hits a part of the sea, the user will get the message "Miss!" on standard output.
    If the missile hits a part of a ship, the user will get the message "Hit!" on standard output.
    If the missile hits a part of a ship, causing it to sink, the user will get the message "Sunk!" on standard output.
    Afterwards the program will behave as if "view board" had been entered by the user.
    stats Print the number of hits, the number of missiles fired, the hit/mis ratio percentage, and the number of ships sunk.
    When computing the percentage for the hit/miss ratio, perform the operation using double precision as follows:
    percentage = numberOfHits / totalMissilesFired * 100
    help List each command and a simple description for the user.
    quit Exit the program.
      If any other command is entered, the user will get the error message "Illegal command." on standard output.
    If the wrong number of arguments is provided to any legitimate command, the user will get the error message "Wrong number of arguments." on standard output.

    If, after a "fire" command, all the battleships are sunk, the game will display, on a separate line,

    You win!

    before the board is displayed. After the board is displayed, the program will behave as if the following commands had been entered by the user:

    1. stats
    2. quit

    Output Format

    When the board is printed, it will be printed as a grid. Rows are horizontal, increasing in coordinates downward, and columns are vertical, increasing in coordinates to the right. Column numbers are displayed above the first row. Row numbers are displayed to the left of the first column. Un-fired-upon water is indicated with a hyphen. Water that has been fired upon is indicated with the letter "O". Un-fired-upon ship locations are indicated by their letters, "A" for length 5, "B" for length 4, "C" for length 3, and "D" for length 2. Ship locations that have been hit by a missile are marked with an "X". All items displayed are placed in a 3-space field, left-justified. Examples are shown elsewhere in this document.

    Project Design

    You are required to use three technologies when designing this lab: inheritance, exceptions, and file input.

    Uses of Inheritance

    1. [Required] You shall use several different classes to represent the current contents of a cell on the board. For example, a class Cell could be an instance of Water, ShipSection (OK or damaged), or MissedMissile.

    2. [Optional] Use several different classes to represent the actions of the six user commands. Populate a container with associations between instances of these new classes and the string name of the first word in each command listed in Figure 2. When the user types something in, a command is looked up and executed.

    Use of Exceptions

    Should an error occur that cannot be handled at the point of detection in the code, an exception should be raised and caught somewhere where the program can gracefully handle it or terminate. For example, you will likely want to use exceptions to deal with file input errors. You may define your own exception classes. Use of System.exit( int ) for any purpose is forbidden in this project.

    Sample Run

    As you follow the sample run below, assume that the file input-2.2 contains the following data:

    5
    2 1 S 4
    2 3 E 3
    7 7 N 5
    5 3 W 2
    7 3 S 2
    

    Any text that the user types in is shown in this way.


    %java Battleship 11 input-2.2
         0  1  2  3  4  5  6  7  8  9 10
      0  -  -  -  -  -  -  -  -  -  -  -
      1  -  -  -  -  -  -  -  -  -  -  -
      2  -  -  -  -  -  -  -  -  -  -  -
      3  -  -  -  -  -  -  -  -  -  -  -
      4  -  -  -  -  -  -  -  -  -  -  -
      5  -  -  -  -  -  -  -  -  -  -  -
      6  -  -  -  -  -  -  -  -  -  -  -
      7  -  -  -  -  -  -  -  -  -  -  -
      8  -  -  -  -  -  -  -  -  -  -  -
      9  -  -  -  -  -  -  -  -  -  -  -
     10  -  -  -  -  -  -  -  -  -  -  -
    > view ships
         0  1  2  3  4  5  6  7  8  9 10
      0  -  -  -  -  -  -  -  -  -  -  -
      1  -  -  -  -  -  -  -  -  -  -  -
      2  -  B  -  C  C  C  -  -  -  -  -
      3  -  B  -  -  -  -  -  A  -  -  -
      4  -  B  -  -  -  -  -  A  -  -  -
      5  -  B  D  D  -  -  -  A  -  -  -
      6  -  -  -  -  -  -  -  A  -  -  -
      7  -  -  -  D  -  -  -  A  -  -  -
      8  -  -  -  D  -  -  -  -  -  -  -
      9  -  -  -  -  -  -  -  -  -  -  -
     10  -  -  -  -  -  -  -  -  -  -  -
    > fire
    Wrong number of arguments.
    > fire 0 0
    Miss!
         0  1  2  3  4  5  6  7  8  9 10
      0  O  -  -  -  -  -  -  -  -  -  -
      1  -  -  -  -  -  -  -  -  -  -  -
      2  -  -  -  -  -  -  -  -  -  -  -
      3  -  -  -  -  -  -  -  -  -  -  -
      4  -  -  -  -  -  -  -  -  -  -  -
      5  -  -  -  -  -  -  -  -  -  -  -
      6  -  -  -  -  -  -  -  -  -  -  -
      7  -  -  -  -  -  -  -  -  -  -  -
      8  -  -  -  -  -  -  -  -  -  -  -
      9  -  -  -  -  -  -  -  -  -  -  -
     10  -  -  -  -  -  -  -  -  -  -  -
    > fire 5 2
    Hit!
         0  1  2  3  4  5  6  7  8  9 10
      0  O  -  -  -  -  -  -  -  -  -  -
      1  -  -  -  -  -  -  -  -  -  -  -
      2  -  -  -  -  -  -  -  -  -  -  -
      3  -  -  -  -  -  -  -  -  -  -  -
      4  -  -  -  -  -  -  -  -  -  -  -
      5  -  -  X  -  -  -  -  -  -  -  -
      6  -  -  -  -  -  -  -  -  -  -  -
      7  -  -  -  -  -  -  -  -  -  -  -
      8  -  -  -  -  -  -  -  -  -  -  -
      9  -  -  -  -  -  -  -  -  -  -  -
     10  -  -  -  -  -  -  -  -  -  -  -
    > fire 5 3
    Hit!
    Sunk!
         0  1  2  3  4  5  6  7  8  9 10
      0  O  -  -  -  -  -  -  -  -  -  -
      1  -  -  -  -  -  -  -  -  -  -  -
      2  -  -  -  -  -  -  -  -  -  -  -
      3  -  -  -  -  -  -  -  -  -  -  -
      4  -  -  -  -  -  -  -  -  -  -  -
      5  -  -  X  X  -  -  -  -  -  -  -
      6  -  -  -  -  -  -  -  -  -  -  -
      7  -  -  -  -  -  -  -  -  -  -  -
      8  -  -  -  -  -  -  -  -  -  -  -
      9  -  -  -  -  -  -  -  -  -  -  -
     10  -  -  -  -  -  -  -  -  -  -  -
    > view ships
         0  1  2  3  4  5  6  7  8  9 10
      0  -  -  -  -  -  -  -  -  -  -  -
      1  -  -  -  -  -  -  -  -  -  -  -
      2  -  B  -  C  C  C  -  -  -  -  -
      3  -  B  -  -  -  -  -  A  -  -  -
      4  -  B  -  -  -  -  -  A  -  -  -
      5  -  B  D  D  -  -  -  A  -  -  -
      6  -  -  -  -  -  -  -  A  -  -  -
      7  -  -  -  D  -  -  -  A  -  -  -
      8  -  -  -  D  -  -  -  -  -  -  -
      9  -  -  -  -  -  -  -  -  -  -  -
     10  -  -  -  -  -  -  -  -  -  -  -
    > stats
    Number of missiles fired: 3
    Hit ratio: 66.66666667%
    Number of ships sunk: 1
    > help
    Possible commands:
    view board - displays the user's board
    view ships - displays the placement of the ships
    fire r c - fires a missile at the cell at [r,c]
    stats - prints out the game statistics
    quit - exits the game
    > abacab
    Illegal command.
    >
    > quit
    


    Tips

    To be able to randomly place the ships correctly the following steps will help you write your code:

    1. For each ship you create, randomly pick a starting location, a length, and a direction.
    2. Ensure that it fits on the board and does not overlap other ships. If that is not so, return to step 1.
    3. Add the ships to a list of ships or mark the cells it occupies on the board.

    Project Submission

    Minimal Submission

    In order to meet minimum submission qualifications you must submit the following:

    When you have these classes working to the standard set by your professor, submit all your source code using the following command:

    try 232-grd project1-min Battleship.java ...

    The ellipsis ("...") means that you may submit as many other java files as your design requires.

    Final Submission

    When you are satisfied and confident that your project meets final submission standards, submit all your source code using the following command:

    try 232-grd project1 Battleship.java ...

    $Id: writeup.html,v 1.5 2005/12/08 18:20:54 vcss232 Exp vcss232 $