UserGuide.adoc

Battleship - User Guide

By: Team W14-3 Since: Jan 2019 Licence: MIT

• 1. Introduction
• 2. Quick Start
• 3. Game Rules
• 4. Features
  • 4.1. General commands
    • 4.1.1. Viewing help : help
    • 4.1.2. Exiting the program : exit
  • 4.2. Preparation phase
    • 4.2.1. Initialising the maps : init
    • 4.2.2. Managing ships: put, list, listTags
      • 4.2.2.1. Placing a ship on the map: put
      • 4.2.2.2. Listing all ships : list
      • 4.2.2.3. Listing all tags: listTags
  • 4.3. Battle phase
    • 4.3.1. Beginning the battle: begin
    • 4.3.2. Shooting at a coordinate: shoot
    • 4.3.3. Retrieving game statistics: stats
• 5. Features Coming in v2.0
  • 5.1. Special map shapes
  • 5.2. Quick start
  • 5.3. Save and load pattern of deployed ships
  • 5.4. Display high score across games
• 6. Command Summary

1. Introduction

Ships ahoy! Battleship is a simple computer-based remake of the classic Battleship game.

It is for people who want to experience the joy of playing Battleships without the hassle and fuss of dealing with physical game pieces.

Battleship is optimised for people who want to use a Command Line Interface (CLI), while still retaining the benefits of a Graphical User Interface (GUI).

It’s a single-player game, and provides a fully functional computerised enemy player for the player to play against, guaranteeing many hours of fun! Can’t wait to get started? Head over to Section 2, “Quick Start” to fire away!

ℹ️

What is a Command Line Interface (CLI) and a Graphical User Interface (GUI)? An interface is how a user interacts with the computer. For example, you can use a mouse to click on a file to open it in Windows or MacOS. This is part of the interface for these operating systems. A Command Line Interface (CLI) interacts with the user by accepting words that are typed in by the user. Conversely, a Graphical User Interface (GUI) interacts with the user visually. It uses icons and graphics to show the user what the program is doing.

As you will see, Battleship is a hybrid application. It combines both a CLI and GUI, meaning that the user must type in commands but will see the changes caused by those commands graphically.

2. Quick Start

1. Ensure you have Java version 9 or later installed in your Computer.

2. Download the latest battleship.jar here.

3. Copy the file to the folder you want to use as the home folder for Battleship.

4. Double-click the file to start the app. The GUI should appear in a few seconds.

5. Type commands in the command box and press Enter to execute them.
   e.g. typing help and pressing Enter will open the help window.

6. Initialise the map to a size between 6 to 10. eg: init 6.

7. Deploy your battleships:

   1. Deploy your aircraft carrier: put n/aircraft carrier c/a1 r/h

   2. Deploy your cruiser(s): put n/cruiser c/c1 r/h

   3. Deploy your destroyer(s): put n/destroyer c/e1 r/h

8. Start the game: start game

9. Shoot the enemy’s map at a specific cell. eg: shoot a1

The game will go on until either party’s ships are totally destroyed.

Refer to Section 4, “Features” for details of each command.

3. Game Rules

This section will describe the game rules and how to play the classic Battleship game.

Goal

Sink all your opponent’s ships before they sink yours.

Captain, deploy ships!

Depending on the chosen size of the map, as specified through the init <map_size> command, you will be given different numbers of each ship.

The ships available are:

• Cruiser: size 2

• Destroyer: size 3

• Aircraft Carrier: size 5

Depending on your map size, your fleet will have different numbers of each ship.

Ready, aim, fire!

After you have placed all your ships, enter begin to start the battle.

You will always be given the first turn. You may fire shots at the enemy map through the command shoot, for example shoot a1.

If the shot hits a ship, you may continue taking shots until they miss. Upon a miss, the turn will be handed over to the enemy. The same goes for the enemy - the enemy will take its shot automatically, firing until it misses, before passing the turn back to you.

Good Game!

Whoever is first to destroy all their opponent’s ships will be declared the winner. Had fun? You can view the game statistics with the command stats.

4. Features

This section will describe the features of the game in more detail.

Command Format

• Words in UPPER_CASE are the parameters to be supplied by you e.g. in init MAP_SIZE, MAP_SIZE is a parameter which can be used as init 10.

• Items in square brackets are optional e.g put n/NAME [t/TAG] can be used as put n/Destroyer t/bestship or as put n/Destroyer.

• Items with …​ after them can be used multiple times including zero times e.g. [t/TAG]…​ can be used as   (i.e. 0 times), t/alpha, t/best t/captain etc.

• Parameters can be in any order e.g. if the command specifies n/NAME c/COORDINATES, c/COORDINATES n/NAME is also acceptable.

ℹ️	Pressing the ↑ and ↓ arrows will display the previous and next input respectively in the command box.

ℹ️	Some commands can only be executed at some part of the game, e.g. attack can only be executed when the battle is ongoing. If you try to enter a command that is not allowed at that point in time, the program will tell you so.

4.1. General commands

This section describes commands that can be executed at any point of time during the game.

4.1.1. Viewing help : help

Opens a help window that displays this User Guide.
Format: help

4.1.2. Exiting the program : exit

Exits the program.
Format: exit

4.2. Preparation phase

This section describes the commands used in the preparation phase.

4.2.1. Initialising the maps : init

The init command initialises both your map and the enemy AI’s map to the size that you specify. The size of the maps must be between 6 and 10, inclusive.

Format: init MAP_SIZE
Example: init 10

• The init command can be used at any point in time during gameplay. When used in the middle of a game, the init command functions like a "new game" command and will reset the board to a clean state.

• Each cell is represented by its coordinates e.g "b1". The coordinates will be used by the other commands to refer to a cell.

Figure 1 below shows how the maps will be displayed in the UI.

Figure 1. The maps as displayed in the UI

Throughout the course of the game, the cells in the map will change colour based on their status.

ℹ️

Cell statuses: Hidden - Enemy map cell that has not been hit Water - Empty (i.e cell with no ship) player cell that has not been hit Water Hit - Empty cell that has been hit Ship - Player cell that has a ship and has not been hit Ship Hit - Ship cell that has been hit but not yet destroyed Ship Destroyed - Ship cell that has been destroyed

Figure 2 below shows which colour is used for each status.

Figure 2. Cell colours

4.2.2. Managing ships: put, list, listTags

4.2.2.1. Placing a ship on the map: put

Adds a ship onto your map. The coordinates specified is the position of the ship’s head.

Format: put n/NAME c/COORDINATES r/ORIENTATION [t/TAGS]

Examples:

• put n/destroyer c/a1 r/vertical

• put n/aircraft carrier c/b1 r/h t/tag1
  

The head of a ship is the top-most and left-most cell of the ship. When coordinates are specified in the put command, it specifies the coordinates of the head of the ship, as shown in the figure below.

Figure 3. The coordinates of the put command refer to the coordinates of the ship head.

The orientation of the ship can be horizontal or vertical. This may be shortened to h or v, respectively. The orientation of the ship must be specified.

When putting a ship on the map grid, you should specify the head coordinates such that:

• The ship falls within the map grid.

• The ship does not collide with another ship that is already on the map grid.

4.2.2.2. Listing all ships : list

Shows a list of all of your ships that have been deployed on the map. There are four ways of using the list command:

1. List all ships: list.

2. List ships that match certain tags: list t/[TAGS].

3. List certain ships: list n/[NAME].

4. List certain ships that match certain tags: list n/[NAME] t/[TAGS]

Examples:

• list

• list t/blueFleet

• list n/destroyer

• list n/destroyer n/cruiser t/blueFleet t/greenFleet

The list will show the ship’s head coordinate, the ship’s orientation, and the ship’s tags in square brackets. The format of each entry in the list is: [NAME] [CURRENT LIFE] at [HEAD COORDINATE] [ORIENTATION] [TAGS]. An example is given below.

Input:      list n/destroyer t/blueFleet t/greenFleet
Output:     destroyer (3/3) at g5 vertical [redFleet][blueFleet][greenFleet]
            destroyer (3/3) at c3 horizontal [blueFleet][greenFleet]

4.2.2.3. Listing all tags: listTags

Lists all the tags that have been used to tag the ship deployed on the map.

Format: listTags

4.3. Battle phase

4.3.1. Beginning the battle: begin

Begins the battle against the computer enemy.
Format: begin
Alternative command: start

• After this command is entered, the program’s AI will place its own ships.

• After the AI completes its placing of ships, you can take your first turn.

4.3.2. Shooting at a coordinate: shoot

Launches an attack against given coordinate on the enemy’s map.
Format: shoot COORDINATES
Alternative commands: attack, fire, hit

Examples:

• shoot a6

• attack b5

• The program will prevent you from attacking an invalid coordinate.

• The program will prevent you from attacking a square that you have already attacked.

• If you hit one of the opponent’s ships, you may make another attack. Otherwise, the enemy will take their turn(s), firing until they get a miss.

4.3.3. Retrieving game statistics: stats

Retrieves the gameplay statistics data displays them on a pop-up window.

Format: stats

• The pop-up window will contain a bar chart visualisation of your game play data

• To reload the statistics data, you must close the current pop-up window and call the stats command again to display the updated values.

5. Features Coming in v2.0

This section describes features that have not been implemented yet and are scheduled to be released in version 2.0.

5.1. Special map shapes

You will be allowed to use maps that are randomised in shape. This adds an extra layer of challenge and fun.

Both yourself and the enemy AI will not be able to place ships on the grey tiles. The enemy AI will also have a randomised map that will not be the same as your map. You will not be able to see the shape of the enemy map and can shoot grey cells which will be counted as a miss.

The image below shows an example of a randomised map.

Figure 4. Example of a random map shape

5.2. Quick start

Randomly deploys the all of your ships onto the map and starts the battle.

Format: quickStart

5.3. Save and load pattern of deployed ships

Save and load the pattern that you used to deploy your ships.

Format: pattern i/OPTION p/PATTERN]
Examples:

• pattern i/save

• pattern i/load p/circle

5.4. Display high score across games

Display the high score across more than two games.

Format: stats highscore t/ATTRIBUTE
Examples:

• stats highscore t/time
  Display game data from the game that won in the shortest amount of time

• stats highscore t/accuracy
  Display game data from the game with the highest accuracy.

6. Command Summary

Feature	Format	Purpose	Example
Attack	attack COORDINATE	Attacks a selected cell on the enemy map.	attack c1
Display manual	help	Opens up the help guide window.	help
Create map of size 6-10	init MAP_SIZE	Initializes the map grid.	init 8
List ships	list [n/NAME] [t/TAG]…	Lists all available ships, optionally filtering by name and tag(s)	list
List tags	listTags	Lists all tags.	listTags
Put ship on map	put n/NAME r/ORIENTATION c/COORDINATE [t/TAG]…	Places a ship on the specified position on the map, optionally adding tag(s).	put n/Destroyer r/vertical c/a1 t/myfleet
View statistics	stats	Opens the Statistics window.	stats
Start battle	start	Begins the battle.	start