Battleships Quick Reference Guide

Understanding The Gamestate

Your calculateMove() function within battleships_move.py will be passed the current state of the game, the 'gamestate'. The gamestate is a python dictionary containing the following keys:

  • Ships - A list of integer lengths of ships that both you and your opponent are expected to place on the board.
  • IsMover - A Boolean value indicating whether it is your turn to move. It will always be true when in the calculateMove() function. (Delve deeper into the code if you want to do some processing during your opponent's turn.)
  • Round - An integer value of 0 or 1, with 0 representing the ship placement round and 1 representing the ship hunting round.
  • ResponseDeadline - The epoch time, in milliseconds, that a successful move has to be sent and received by to prevent you from timing out.
  • DealNumber - Which deal you are up to in the match, this key only appears when the value of DealsTotal is greater than 1.
  • DealsTotal - The total number of times you are going to play a whole game of Battleships in this match, this key only appears when the value is greater than 1.
  • MyScore - Your current score in this game, increases by one for every deal you win. The player with the largest score at the end wins.
  • OppScore - Your opponent's current score in this game, increases by one for every deal they win. The player with the largest score at the end wins.
  • MyBoard - A 2-dimensional array of strings representing the state of your board. (See Understanding The Boards)
  • OppBoard - A 2-dimensional array of strings representing the state of your opponent's board, with their ships hidden of course. (See Understanding The Boards)
  • GameStatus - A string that will have value "RUNNING" if the game is in progress or a reason the game has ended otherwise.
  • GameId - An integer representing the unique game id for the current game.
  • OpponentId - A string containing the name of your opponent.

Understanding The Boards

The strings in your board can contain the following values:

  • "" - A cell that hasn't been hit that contains nothing on your board, or contains unknown on your opponent's board.
  • "L" - A cell containing land that hasn't been hit.
  • "M" - A cell containing nothing that has been hit.
  • "LM" - A cell containing land that has been hit. (Why are you firing at land?)
  • "H" - A cell on your opponent's board containing a ship that has been hit.
  • "Hx" - A cell on your board containing ship number x that has been hit.
  • "Sx" - A cell on either player's board containing ship number x that has been sunk.
  • "x" - A cell on your board containing ship number x.

Making A Valid Move

Depending on which round you are in the value you have to return from the calculateMove() function is as follows:

  • If you are in the ship placement round your move should be a dictionary with key name 'Placement' and value Move. Move is a list of dictionaries, one for each ship, with the following key value pairs:
    • 'Row' which takes values 'A','B',etc.
    • 'Column' which takes values 1,2,etc.
    • 'Orientation' which take values 'H' or 'V'.
  • If you are in the ship hunting round your move should be a dictionary with the following key value pairs:
    • 'Row' which takes values 'A','B',etc.
    • 'Column' which takes values 1,2,etc.

Here is an example of a valid ship placement move:

# The Placement list adds ships in the order that the ships are 
# listed in the game style e.g. 5,4,3,3,2 places the ship of length 
# 5 first, the ship of length 4 second, the ship of length 3 third.
# 
# This function does not check for any land and, so, should be used
# with a gamestyle that does not include land.
{"Placement": [
      {
        "Row": "A",
        "Column": 1,
        "Orientation": "H"
      },
      {
        "Row": "B",
        "Column": 6,
        "Orientation": "V"
      },
      {
        "Row": "C",
        "Column": 1,
        "Orientation": "H"
      },
      {
        "Row": "D",
        "Column": 1,
        "Orientation": "H"
      },
      {
        "Row": "E",
        "Column": 1,
        "Orientation": "V"
      }
   ]
}

And a valid ship hunting move:

{
    "Row": "B",
    "Column": 4
}

Helper Functions

  • deployRandomly(gamestate) - Given the current gamestate, returns a valid move that deploys all the ships randomly on a blank board.
  • deployShip(i, j, board, length, orientation, ship_num) - Returns whether a given location (i,j) and orientation ("H", "V") can fit a given ship (ship_num) onto given board and, if it can, updates the given board with that ship's position.
  • chooseRandomValidTarget(gamestate) - Given the current gamestate, returns a valid move that randomly guesses a location on the board that hasn't already been hit.
  • shipsStillAfloat(gamestate) - Given the current gamestate, returns a list of the lengths of your opponent's ships that haven't been sunk.
  • selectUntargetedAdjacentCell(row, column, oppBoard) - Returns a list of cells adjacent to the input cell that are free to be targeted (not including land).
  • translateMove(row, column) - Given a valid coordinate on the board returns it as a correctly formatted move.

Jargon:

  • Ship placement round - The first move in a game of battleships where you choose where you wish to place your ships.
  • Ship hunting round - All subsequent moves where you guess a location you think your opponent's ships may be.
  • Epoch time - The number of seconds (or in our case milliseconds) that have elapsed since January 1 1970 00:00 UTC.
iconBattleshipsBlack.png
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License