Programmer's Reference

SG
Last updated last month

Each game has its own version of the gamestate JSON and move JSON with fields that are specific to that game. Each game's requirements are described on this page.

Introduction

Each game has its own specific information and this is passed to it in the gamestate. This means that the gamestate has different fields in it for each game. The gamestate for each game is detailed below.

You may not need to use some of the fields in the gamestate for different games. For example, you may never be interested in the GameId field. For the majority of games you may not be interested in the GameStatus field, but, for a very few games, this can be used to help make decisions.

Battleships

gamestate

Example gamestate JSON

{
'Ships': [5, 4, 3, 3, 2],
'IsMover': True,
'Round': 1,
'ResponseDeadline': 1543861722513,
'MyScore': 0,
'OppScore': 0,
'MyBoard': [
['L', 'L', '0', 'H0', 'H0', 'H0', '0', ''],
['L', 'L', '1', 'H1', 'H1', 'H1', '', ''],
['L', 'L', '', 'M', '', '', '', ''],
['L', 'L', '', '', '', '', '', ''],
['L', 'L', 'L', 'L', '', '', '', ''],
['L', 'L', 'L', 'L', '', '', '4', '2'],
['', '', '3', '3', '3', '', '4', '2'],
['', '', '', 'M', 'M', '', '', '2']
],
'OppBoard': [
['L', 'L', '', '', '', '', '', ''],
['L', 'L', '', '', '', '', '', ''],
['L', 'L', 'M', '', '', '', '', 'M'],
['L', 'L', '', '', 'H', 'H', '', ''],
['L', 'L', 'L', 'L', '', 'H', 'M', ''],
['L', 'L', 'L', 'L', '', '', '', ''],
['', 'M', '', '', '', '', '', 'M'],
['', '', '', '', '', '', 'M', '']
],
'GameStatus': 'RUNNING',
'GameId': 2398045,
'OpponentId': 'housebot-practise'
}

A description of each field in the gamestate.

Key

Description

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 calculate_move() 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

OppBoard

A 2-dimensional array of strings representing the state of your opponent's board, with their ships hidden of course

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.

Ship Placement Move

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"
}
]
}

Ship Hunting Move

Here is an example of 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.

Blurry Words

gamestate

Here is an example of the gamestate JSON

{
'Images': [
'https://s3.eu-west-2.amazonaws.com/aigaming/WordPuzzleGame/Images/ba41ea2e-27b7-4f2a-bc54-5ad6ec84d746/s0.jpeg',
'https://s3.eu-west-2.amazonaws.com/aigaming/WordPuzzleGame/Images/ba41ea2e-27b7-4f2a-bc54-5ad6ec84d746/s1.jpeg',
'https://s3.eu-west-2.amazonaws.com/aigaming/WordPuzzleGame/Images/ba41ea2e-27b7-4f2a-bc54-5ad6ec84d746/s2.jpeg'
],
'EndTime': 1543915708520,
'GameLength': 17000,
'IsMover': True,
'MyAnswers': ['', '', ''],
'OppAnswers': ['', '', ''],
'MyDistances': [52, 67, 48],
'OppDistances': [52, 67, 48],
'GameStatus': 'RUNNING',
'GameId': 2398324,
'OpponentId': 'housebot-practise'
}

A description of each field in the gamestate

Images

A list containing http links to the three images you must process

EndTime

The epoch time, in milliseconds at which this game will end

Gamelength

The total game length in milliseconds

IsMover

A boolean that represents whether you can submit a route. Always set to True as long as game is running

MyAnswers

A list of your best solutions so far for each of the sentences. If you have not submitted a solution the string will be blank ie ''.

OppAnswers

A list of your opponents best answers so far. If they have not submitted a solution the string will be blank ie ''

MyDistances

A list of your current Levenshtein distances from the correct solution. A score of 0 represents you have the correct answer. For more information on how the Levenshtein distance is calculated see the challenge home page

OppDistances

A list of your opponents current Levenshtein distances from the correct solution

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

Checkers

gamestate

An example of the gamestate JSON

{
'Board': [
[-1, -1, -1, 3, -1, -1, -1, 0],
[3, -1, -1, -1, 1, -1, 0, -1],
[-1, -1, -1, -1, -1, -1, -1, -1],
[0, -1, -1, -1, -1, -1, -1, -1],
[-1, -1, -1, 0, -1, -1, -1, -1],
[-1, -1, -1, -1, -1, -1, -1, -1],
[-1, 1, -1, 1, -1, 1, -1, -1],
[1, -1, 1, -1, 1, -1, -1, -1]
],
'Role': 0,
'PossibleMoves': {
'[1, 6]': [
[2, 7],
[2, 5]
],
'[3, 0]': [
[4, 1]
],
'[4, 3]': [
[5, 4],
[5, 2]
]
},
'IsMover': True,
'ResponseDeadline': 1543861883390,
'GameStatus': 'RUNNING',
'Steps': 34,
'GameId': 2398046,
'OpponentId': 'housebot-practise'
}

A description of each of the gamestate fields

Key

Description

Board

A list of lists representing each row on the board

Role

Whether you are the Dark or Light player. The Light player moves first

PossibleMoves

A list of lists containing every valid move that can be made at this point in the game

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)

ResponseDeadline

The epoch time, in milliseconds, that a successful move has to be sent and received by to prevent you from timing out

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:

  • -1 - A cell that has not have a piece on it.

  • 0 - A cell that has a Light coloured regular piece on it.

  • 1 - A cell that has a Dark coloured regular piece on it.

  • 2 - A cell that has a Light coloured King piece on it.

  • 3 - A cell that has a Dark coloured King piece on it

Making a valid move

Dominoes

gamestate

An example of the gamestate JSON

{
'IsMover': True,
'ResponseDeadline': 1543935386057,
'GameStatus': 'RUNNING',
'first_center_dominoes': [3, 6],
'center_dominoes': [
[3, 2],
[2, 1],
[1, 1],
[1, 5],
[5, 0],
[0, 4],
[4, 3],
[3, 6],
[6, 1],
[1, 4]
],
'oppo_dominoes_number': 1,
'MyDominoes': [
[2, 2],
[6, 6],
[2, 6],
[1, 3]
],
'number_of_spots': 7,
'dominoes_remainder': 13,
'GameId': 2398471,
'OpponentId': 'housebot-practise'
}

A description of each field in the gamestate

Key

Description

MyDominoes

A 2-dimensional array of integers representing the the dominoes in your hand.

IsMover

A Boolean value indicating whether it is your turn to move. It will always be true when in the calculate_move() function

ResponseDeadline

The epoch time, in milliseconds, that a successful move has to be sent and received by to prevent you from timing out

first_center_dominoes

the first domino added to the domino board at the centre

center_dominoes

All the dominoes in the domino board.

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 board

Each domino for now only has 6 dots at maximum on the top or at the bottom of the domino.

An example of the centre_domino:

[ [4,0], [0,3], [3,6], [6,4], [4,4], [4,3] ]

Would visually be displayed as follows:

The domino in red block is the first_centre_domino.

An example of the MyDomino:

[ [1,6], [2,2], [6,0] ]

Would visually be displayed as follows:

Making a Valid Move

The value you have to return from the calculateMove() function is a dictionary states the domino you want to move and the position you want it to move to.

The suitable_domino should be in your hand and the "Position" should be either "R" or "L"

Here is an example of valid moves:

move = { " suitable_domino": [2, 1], " Position": “R”}

But the suitable domino must have a number that matches a number on one open end of the domino board and the position should be correctly matched.

Four In A Row

gamestate

An example of the gamestate JSON

{ 'IsMover': True, 'ResponseDeadline': 1543862692119, 'Connections': 4, 'GameStatus': 'RUNNING', 'Board': [ [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [-1, -1, -1, -1, -1, -1, -1], [1, -1, 1, -1, -1, 0, 1], [0, 0, 1, -1, 1, 0, 0] ], 'GameId': 2398056, 'OpponentId': 'housebot-practise'}

A description of each field in the JSON

Key

Description

Connections

An integer that shows how many counters you need to connect to win.

IsMover

A Boolean value indicating whether it is your turn to move. It will always be true when in the calculateMove() function.

ResponseDeadline

The epoch time, in milliseconds, that a successful move has to be sent and received by to prevent you from timing out.

Board

A 2-dimensional array of integers representing the state of the board also see 'Understanding The Board' below.

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 board

An example of the board

[ [-1, 0, 1, 1, -1, -1, -1], [-1, 0, 0, 1, -1, -1, -1], [-1, 0, 0, 0, 1, -1, -1], [-1, 1, 1, 0, 1, -1, -1], [-1, 0, 1, 1, 1, -1, -1], [0, 1, 1, 0, 0, 0, 0]]

Would visually be displayed as follows:

{ 'Board': [ [5, 8, 7], [2, 6, 3], [1, 4, 0] ], 'ResponseDeadline': 1543861424041, 'IsMover': True, 'MyBestSolution': [4, 6, 8, 5, 2, 8, 3, 7, 5, 3, 8, 2, 3, 5, 7, 4, 6, 8, 5, 3, 2, 5, 4, 7, 3, 4, 7, 6, 8, 1, 5, 7, 1, 5, 7, 1, 4, 2, 1, 4, 5, 8], 'OppBestSolution': [3, 7, 8, 5, 2, 1, 4, 3, 7, 6, 3, 7, 6, 8, 5, 3, 8, 5, 3, 2, 1, 4, 7, 8, 5, 6], 'IsLeader': False, 'GameStatus': 'RUNNING', 'GameId': 2398043, 'OpponentId': 'housebot-practise'}

The boards integers in the Gamestate can contain the following values:

  • -1 - A hole that hasn't been used and that contains nothing.

  • 1 - A hole containing one of your counters.

  • 0 - A hole containing one of your opponents counters.

Making a valid move

To submit a move you need to return in calculateMove, an integer of the column you want to place your counter in. This starts with column 0 and the highest column is len(board[0])-1.

You cannot submit a move for a column that is already full. For example:

return {"Column": 4}

Would place a counter in the 5th column from the left. The game goes on until the board is full or a player connects the required number of counters (gamestate['Connections'] which is dependent on the gameStyle).

Go

gamestate

An example of the gamestate JSON

{
'Board': [
[1, -1, 0, -1, -1, -1, -1],
[-1, 0, 0, -1, 1, -1, 0],
[1, 0, 1, 1, -1, 0, 1],
[0, -1, -1, -1, 0, -1, -1],
[-1, -1, 1, 1, 1, -1, -1],
[0, 0, 1, -1, -1, 0, 0],
[-1, 1, -1, 1, 1, -1, -1]
],
'PreviousBoard': [
[1, -1, 0, -1, -1, -1, -1],
[-1, 0, 0, -1, 1, -1, 0],
[-1, 0, 1, 1, -1, 0, 1],
[0, -1, -1, -1, 0, -1, -1],
[-1, -1, 1, 1, 1, -1, -1],
[0, 0, 1, -1, -1, 0, 0],
[-1, 1, -1, 1, 1, -1, -1]
],
'IsMover': True,
'ResponseDeadline': 1543936950967,
'Black': 0,
'MyRole': 0,
'IsCaptureGo': False,
'CaptureTarget': 1,
'MyCaptures': 0,
'OpponentCaptures': 0,
'MaxMoves': 200,
'MoveNumber': 26,
'LastMoveWasPass': False,
'ScoringMethod': 'STONE',
'GameStatus': 'RUNNING',
'GameId': 2398483,
'OpponentId': 'housebot-practise'
}

A description of each field in the gamestate

Key

Description

Board

A 2-dimensional array of integers representing the state of the board.

PreviousBoard

A 2-dimensional array of integers representing the state of the board after your last move. If you are playing Capture Go then this value will always be an empty 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.)

ResponseDeadline

The epoch time, in milliseconds, that a successful move has to be sent and received by to prevent you from timing out

Black

An integer representing the ID of the player who is using black stones. It will be either `0` or `1`.

MyRole

An integer representing your ID (`0` or `1`).

IsCaptureGo

A Boolean value indicating whether the game style you are playing is Capture Go

CaptureTarget

An integer representing the target number of stones to capture throughout the game in order to win. If you are not playing Capture Go then this will always be `None`

MyCaptures

An integer representing the number of stones you have captured so far in this game. If you are not playing Capture Go then this will always be `0`.

OpponentCaptures

An integer representing the number of stones captured by your opponent so far in this game. If you are not playing Capture Go then this will always be `0`.

MaxMoves

An integer representing the maximum number of moves allowed in the game from start to end. Once there have been this many moves the game will end. If you are playing Capture Go then this will always be `False`

MoveNumber

The number of the move you are to make. If you are making the first move of the game then this will be `0`. Thus the value is equivalent to the number of moves that have already happened. If you are playing Capture Go then this will always be `0`

LastMoveWasPass

A Boolean value indicating whether the opponent has just passed their turn. At the start of the game this is `False`

ScoringMethod

A string with value `"STONE"`, `"TERRITORY"`, or `"AREA"` to indicate whether the scoring method for the game is stone scoring, territory scoring, or area scoring. If you are playing Capture Go then this will always be `None`.

GameStatus

A string that will have value "RUNNING" if the game is in progress, or a reason the game has ended otherwise

Understanding The Board

The Board and the PreviousBoard 2-dimensional arrays in the gameState can contain the following integer values:

  • -1 An empty (that is, unoccupied) intersection.

  • 0 An intersection occupied by a stone belonging to the player with ID 0.

  • 1 An intersection occupied by a stone belonging to the player with ID 1.

Making A Valid Move

The value you have to return from the calculateMove() function is a dictionary which either specifies a location (X, Y) on the board to place a stone, or the location (-1, -1), indicating that you wish to pass your turn. The dictionary must have the following key value pairs:

  • "X" which takes values -1, 0, 1, 2, etc.

  • "Y" which takes values -1, 0, 1, 2, etc.

Here is an example of a valid move:

`{ "X": 0, "Y": 0 }`

Microsoft Match Game

gamestate

Example of the gamestate JSON

{
'Board': [0, 0, 0, 1, 0, 0, 1, 0, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1],
'MyPoints': 3,
'OppPoints': 1,
'UpturnedTiles': [{
'Index': 4,
'Tile': 'https://s3.eu-west-2.amazonaws.com/aigaming/Pairs/Games/5a39ebe4-6396-44d0-8b2f-9d113552f2ff/095726b5-b151-4c05-b89f-b1cc260553c8.jpg'
}, {
'Index': 14,
'Tile': 'https://s3.eu-west-2.amazonaws.com/aigaming/Pairs/Games/5a39ebe4-6396-44d0-8b2f-9d113552f2ff/dc23c9ae-2d95-4ee7-8f4e-1b31cfdbe0ca.jpg'
}],
'CategoryList': ['Words', 'Animals', 'Landmarks'],
'OpponentMatches': 2,
'TileBacks': [
'https://s3.eu-west-2.amazonaws.com/aigaming/Pairs/Games/5a39ebe4-6396-44d0-8b2f-9d113552f2ff/2f70f0e9-671a-4b9d-a0a8-d14fab82d6a9.png',
'https://s3.eu-west-2.amazonaws.com/aigaming/Pairs/Games/5a39ebe4-6396-44d0-8b2f-9d113552f2ff/2f70f0e9-671a-4b9d-a0a8-d14fab82d6a9.png',
'https://s3.eu-west-2.amazonaws.com/aigaming/Pairs/Games/5a39ebe4-6396-44d0-8b2f-9d113552f2ff/22ab57c2-e1a7-4fe6-a161-6df00526a8d4.png',
'https://s3.eu-west-2.amazonaws.com/aigaming/Pairs/Games/5a39ebe4-6396-44d0-8b2f-9d113552f2ff/4bca2bde-be63-468f-88f7-99fcaeaebeca.png',
'https://s3.eu-west-2.amazonaws.com/aigaming/Pairs/Games/5a39ebe4-6396-44d0-8b2f-9d113552f2ff/2f70f0e9-671a-4b9d-a0a8-d14fab82d6a9.png',
'https://s3.eu-west-2.amazonaws.com/aigaming/Pairs/Games/5a39ebe4-6396-44d0-8b2f-9d113552f2ff/2f70f0e9-671a-4b9d-a0a8-d14fab82d6a9.png',
'https://s3.eu-west-2.amazonaws.com/aigaming/Pairs/Games/5a39ebe4-6396-44d0-8b2f-9d113552f2ff/4bca2bde-be63-468f-88f7-99fcaeaebeca.png',
'https://s3.eu-west-2.amazonaws.com/aigaming/Pairs/Games/5a39ebe4-6396-44d0-8b2f-9d113552f2ff/2f70f0e9-671a-4b9d-a0a8-d14fab82d6a9.png',
'https://s3.eu-west-2.amazonaws.com/aigaming/Pairs/Games/5a39ebe4-6396-44d0-8b2f-9d113552f2ff/2f70f0e9-671a-4b9d-a0a8-d14fab82d6a9.png',
'https://s3.eu-west-2.amazonaws.com/aigaming/Pairs/Games/5a39ebe4-6396-44d0-8b2f-9d113552f2ff/2f70f0e9-671a-4b9d-a0a8-d14fab82d6a9.png',
'https://s3.eu-west-2.amazonaws.com/aigaming/Pairs/Games/5a39ebe4-6396-44d0-8b2f-9d113552f2ff/4bca2bde-be63-468f-88f7-99fcaeaebeca.png',
'https://s3.eu-west-2.amazonaws.com/aigaming/Pairs/Games/5a39ebe4-6396-44d0-8b2f-9d113552f2ff/2f70f0e9-671a-4b9d-a0a8-d14fab82d6a9.png',
'https://s3.eu-west-2.amazonaws.com/aigaming/Pairs/Games/5a39ebe4-6396-44d0-8b2f-9d113552f2ff/2f70f0e9-671a-4b9d-a0a8-d14fab82d6a9.png',
'https://s3.eu-west-2.amazonaws.com/aigaming/Pairs/Games/5a39ebe4-6396-44d0-8b2f-9d113552f2ff/4bca2bde-be63-468f-88f7-99fcaeaebeca.png',
'https://s3.eu-west-2.amazonaws.com/aigaming/Pairs/Games/5a39ebe4-6396-44d0-8b2f-9d113552f2ff/2f70f0e9-671a-4b9d-a0a8-d14fab82d6a9.png',
'https://s3.eu-west-2.amazonaws.com/aigaming/Pairs/Games/5a39ebe4-6396-44d0-8b2f-9d113552f2ff/2f70f0e9-671a-4b9d-a0a8-d14fab82d6a9.png',
'https://s3.eu-west-2.amazonaws.com/aigaming/Pairs/Games/5a39ebe4-6396-44d0-8b2f-9d113552f2ff/4bca2bde-be63-468f-88f7-99fcaeaebeca.png',
'https://s3.eu-west-2.amazonaws.com/aigaming/Pairs/Games/5a39ebe4-6396-44d0-8b2f-9d113552f2ff/22ab57c2-e1a7-4fe6-a161-6df00526a8d4.png',
'https://s3.eu-west-2.amazonaws.com/aigaming/Pairs/Games/5a39ebe4-6396-44d0-8b2f-9d113552f2ff/2f70f0e9-671a-4b9d-a0a8-d14fab82d6a9.png',
'https://s3.eu-west-2.amazonaws.com/aigaming/Pairs/Games/5a39ebe4-6396-44d0-8b2f-9d113552f2ff/4bca2bde-be63-468f-88f7-99fcaeaebeca.png'
],
'IsMover': True,
'ResponseDeadline': 1543862250328,
'GameStatus': 'RUNNING',
'AnimalList': ['cat', 'dog', 'horse', 'lion', 'turtle', 'deer', 'zebra',
'rhinoceros', 'fox', 'cow', 'chicken', 'sheep', 'antelope', 'ape', 'bear',
'cheetah', 'donkey', 'eagle', 'echidna', 'elephant', 'flamingo', 'giraffe',
'goat', 'hawk', 'heron', 'hummingbird', 'kangaroo', 'koala', 'leopard',
'meerkat', 'ostrich', 'owl', 'parrot', 'penguin', 'phasianid', 'rodent',
'salamander', 'seal', 'snake', 'squirrel', 'tiger', 'vulture', 'wolf'],
'Bonus': 'Landmarks',
'Multiplier': 1,
'GameId': 2398049,
'OpponentId': 'housebot-practise'
}

Description of each of the gamestate fields

Key

Description

Board

A list representing each tile in the game and whether that tile has been successfully matched or not. A "1" means the tile has been matched and "0" means the tile has not yet been matched.

  • An example of the Board data could be 'Board':[0, 0, 1, 0, 0, 1, 1, 0, 1, 0, 0, 0, 1, 0, 0, 0]

  • You could use the Board data to determine how many sets need to be matched by calling len(gamestate["Board"])

  • You would access a specific item in the list using gamestate["Board"][7]. This would give you the 8th item in the list.

UpturnedTiles

A list of dictionaries detailing the upturned tiles for this move.

  • The upturned tiles will be the tiles you submitted as your previous move. If your previous move was Tiles: [1,10] then you will receive the image url for tile 1 and for tile 10 in the UpturnedTiles field.

  • If there are upturned tiles, there will always be two upturned tiles.

  • Each upturned tile states the Index of the tile, which is its unique location, and a URL to the image that is on the tile. It is this image that you need to analyse and match.

  • An example of accessing an upturned tiles URL would be gamestate["UpturnedTiles"][0]["Tile"]

TileBacks

A list of strings containing the URLs of the images for the backs of the tiles.

AnimalList

A list of strings that details all possible animals that will be displayed in the game.

  • To identify that the tile image you have analysed is a picture of an animal, you can search through the tags returned from the Microsoft API to see if any of the tags contain an animal name in the AnimalList.

  • You can check to see if the name of an animal exists in the AnimalList using if "elephant" in gamestate["AnimalList"]:

CategoryList

A list of strings that details all possible categories that tiles will belong to in the game.

  • Each tile belongs to one of the categories

  • If you choose tiles that are in the same category, they have a much better chance of matching than if you choose any unmatched tile from any category.

MyPoints

Your current points score for this game

OpponentPoints

Your opponents current points score for this game

OpponentMatches

The number of matched tile sets that your opponent has successfully identified.

  • You can use this value to identify how quickly your opponent is matching tiles

Bonus

A String containing the name of a category. If your move matches tiles in this bonus category, the score you receive will be multiplied by the Multiplier amount.

  • For example, this Bonus field might be set to "Landmarks". If you match a pair of Landmark tiles while the Bonus field is set to Landmarks, the score you receive for this move will be multiplied by the Multiplier field value

  • If either you or your opponent match a pair that is in the bonus category, the bonus category will be randomly set to another category in the next move

Multiplier

The current score multiplier that is affected by matching tiles that are in the Bonus Category.

  • Consecutively matching tiles in the bonus category doubles the multiplier.

  • Not matching tiles in the bonus category resets the multiplier.

GameId

An integer representing the unique game id for the current game

  • You are unlikely to need the GameId for this game type

OpponentId

A string containing the name of your opponent

  • You are unlikely to need the OpponentId for this game type

ResponseDeadline

The epoch time, in milliseconds, that a successful move has to be sent and received by to prevent you from timing out.

  • There is a time limit to how long you have to calculate your move. If you exceed this time limit your game will be terminated and your opponent will be awarded as the winner.

  • It is unlikely that you will need to check this time as timeouts are set generously to allow you time to calculate your move, however, if you see yourself timing out a lot, you may need to limit yourself using this value.

GameStatus

A string that will have value "RUNNING" if the game is in progress or a reason the game has ended otherwise.

  • You are unlikely to need the GameStatus for this game type

IsMover

In this turned based game, this will always be true

Making a valid move

The point of the calculate_move() function is for you to return the move you want to make in the game. In the Match Game, a move is the pair of tiles that you want to turn over to see if they match.

You should determine which tiles to turn over by remembering the tiles you have already seen and trying to turn over a pair of tiles that have the same subject.

To submit your move, you return a dictionary with the Key Pair of "Tiles" and then a list of the tiles that you want to turn over. For example:

return {"Tiles": [10, 14]}

Mastermind

gamestate

An example of the gamestate JSON

{
'NumColours': 8,
'NumPegs': 4,
'DuplicatesAllowed': True,
'IsLeading': False,
'Round': 1,
'NumGuesses': 12,
'MyGuesses': 0,
'OppGuesses': 0,
'myFinishedTime': None,
'OppFinishedTime': None,
'EndTime': 1543862748400,
'GameLength': 20000,
'MyScore': 0,
'OppScore': 0,
'IsMover': True,
'GuessesList': [],
'GameStatus': 'RUNNING',
'GameId': 2398057,
'OpponentId': 'housebot-practise'
}

A description of each field in the gamestate

Key

Description

Comparison

A list that contains the results from your last guess. The first number represents the number of correct colours but incorrect position and the second number is where the colour and position are both correct. This entry will only exist once you have submitted at least one guess

NumColours

The number of different colours available for each peg in the hidden sequence

NumPegs

The number of pegs that make up each of the hidden sequences. This value will not change during the game and is determined by the game type you are currently playing.

DuplicatesAllowed

Whether you are allowed duplicate coloured pegs in your hidden sequence. This value will not change during the game and is determined by the game type you are currently playing.

IsLeading

A Boolean value indicating whether you are winning

Round

A number representing the current round of the game. If 0 then you are setting up your hidden sequence. If 1 you are trying to guess your opponents hidden sequence

NumGuesses

The total number of guesses you are allowed to try and find your opponents code. This value will not change during the game and is determined by the game type you are currently playing

MyGuesses

The number of guesses you have currently used

OppGuesses

The number of guesses your opponent has used

myFinishedTime

The epoch time you submitted the correct solution. Set to 'None' if you have not found the solution

OppFinishedTime

The epoch time your opponent submit the correct solution. Set to 'None' if they have not found the solution

GameLength

The game length in milliseconds

MyScore

If playing a series of games this is your running total number of games won

OppScore

If playing a series of games this is your opponents running total number of games won

IsMover

Always set to 'True' whilst the game is in play.

GuessesList

A list of all your previous guesses

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

Making a valid move

There are two different types of moves that you can make in this game. You will either be setting your initial peg sequence that your opponent will need to determine, or, you will be submitting a guessed peg sequence to see if it matches.

Submit your hidden peg sequence

On game startup the 'Round' entry in gameState is set to 0. This move is setting your hidden peg sequence. The sequence is a list of numbers where each number represents a peg and the value of each number can be between 0 and the 'NumColours' minus 1. For example if 'NumPegs'=6 and 'NumColours'=8 a valid move would be:

move = {"Sequence": [0,1,2,3,6,7]}

Submit a Guess

Once the 'Round' entry in gameState is set to 1 then you are trying to guess your opponents hidden sequence. A guess is a list of numbers where each number represents a peg in your opponents sequence. Again each peg can be any value between 0 and the 'NumColours' minus 1. For example if 'NumPegs'=4 and 'NumColours'=6 a valid guess would be:

move = {"Sequence": [2,0,1,5]}

If and when you submit the correct solution calculateMove() will no longer be called and your code will no longer be executed.

Understanding the Comparison Result

Once you have submitted at least one guess the 'Comparison' entry in gameState will have a value. The first number represents the number of correct colours but incorrect position and the second number is where the colour and position are both correct. For example if your opponents secret code is [1,2,3,4] and you guess [1,3,4,5] your comparison result would be [2,1].

Noughts & Crosses

gamestate

An example of the gamestate JSON

{
'Board': [' ', ' ', 'O', 'O', 'X', ' ', ' ', ' ', ' '],
'IsMover': True,
'Role': 'X',
'ResponseDeadline': 1543868919361,
'MyScore': 0,
'OppScore': 0,
'GameStatus': 'RUNNING',
'GameId': 2398094,
'OpponentId': 'housebot-practise'
}

A description of each field in the gamestate

Key

Description

Board

A list of strings representing the state of the board.

IsMover

A Boolean value indicating whether it is your turn to move. It will always be true when in the calculate_move() function

Role

A string of value either "O", indicating you are playing as noughts, or "X", indicating you are playing as crosses

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

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 position that is blank.

  • "O" - A position that contains a nought.

  • "X" - A position that contains a cross.

The indices of the board represent the following positions on the noughts and crosses grid:

Making A Valid Move

The value you have to return from the calculate_move() function is a key value pair, 'Position', which has value equal to the index of the position on the board you wish to make your move:

Here is an example of a valid noughts and crosses move:

{
"Position": 4
}

And its result on a blank board when playing with role "X":

Predictive Text

gamestate

An example of the gamestate JSON

{
'GameStatus': 'RUNNING',
'Redacted': [
['There', 'are', 'certain', 'salmon,', '__', '__', 'mentioned,', 'that', 'never', '__', '__', 'sea', '__', 'all.'],
['__', 'married,', '__', 'the', 'same', 'year,', 'a', 'gentle', 'girl', 'who,', 'from', 'the', 'time', 'she', 'was', 'thirteen,', 'had', 'had', 'mystic', 'visions', 'and', 'experiences', '__', 'religion.'],
['__', 'this', 'way', 'they', 'protect', 'the', 'skin', 'underneath.'],
['__', 'was', 'the', 'god', '__', 'wine,', 'and', 'when', '__', 'grew', '__', '__', 'loved', '__', 'teach', 'men', 'how', '__', 'train', 'the', 'vine', 'and', 'press', 'the', 'juice', 'from', 'the', 'grape.'],
['The', 'cochlear', 'canal', 'contains', 'the', 'little', 'piece', '__', 'machinery', 'that', 'changes', 'the', 'liquid', 'vibrations', 'into', 'sound.']
],
'guesses': [
[
['in', 'is', 'in', 'to', 'in'],
['to', 'to', 'is'],
['in'],
['', '', '', '', '', '', ''],
['']
],
[
['to', 'to', 'is', 'it', 'to'],
['of', '', ''],
[''],
['', '', '', '', '', '', ''],
['']
]
],
'EndTime': 1543940342.1204026,
'IsMover': True,
'PlayerIndex': 0,
'GameId': 2398510,
'OpponentId': 'housebot-practise'
}

A description of each field in the gamestate JSON

Key

Description

GameStatus

A string that will have value "RUNNING" if the game is in progress or a reason the game has ended otherwise

Redacted

The list of sentences to identify either the missing two letter words or the incorrect two letter words. If the game type is missing words then each missing word will be identified in the list as '__'.

guesses

A two part list that contains your and your opponents current guesses. The position in the list is determined by your PlayerIndex value e.g. if you are PlayerIndex 0 then your list of guesses will be the first in the list

EndTime

The epoch time, in milliseconds at which this game will end

IsMover

A boolean that represents whether you can submit a guess. Always set to True as long as game is running

PlayerIndex

Your player index reference this can be either 0 or 1

GameId

An integer representing the unique game id for the current game

OpponentId

A string containing the name of your opponent

Understanding the board

Understanding the List of Sentences

The list contained in Redacted is the list of words that make up each sentence. For example if you are playing the missing word game your list of sentences could look like this:

[['Columbus', 'and', 'his', 'crew', 'knew', 'a', 'number', '__', 'things', 'before', 'they', 'raised', 'their', 'anchor.'], ['Through', 'the', 'brief', 'summer', 'the', 'family', 'had', '__', 'toil', '__', 'lay', '__', 'crops', 'against', 'the', 'long', 'hard', 'winter.'], ['Edge', '__', 'the', 'arch', 'between', 'the', 'pharynx', 'and', 'soft', 'palate.'], ['__', '__', 'very', 'extensible,', 'and', 'that', '__', 'what', 'made', '__', 'astonish', 'its', 'discoverers', '__', 'its', 'bouncing.'], ['They', 'give', '__', 'a', 'quality', '__', 'resilience,', '__', 'spring,', 'while', 'still', 'supporting', 'it.']]

Understanding the List of Guesses

Initially this will contain a list of empty strings with the correct number of entries depending on how many two letter words are in each sentence. Every time you or your opponent submit a guess this list will be filled out with the submissions. So with a list of sentences as follows:

[['Columbus', 'and', 'his', 'crew', 'knew', 'a', 'number', '__', 'things', 'before', 'they', 'raised', 'their', 'anchor.'], ['Through', 'the', 'brief', 'summer', 'the', 'family', 'had', '__', 'toil', '__', 'lay', '__', 'crops', 'against', 'the', 'long', 'hard', 'winter.'], ['Edge', '__', 'the', 'arch', 'between', 'the', 'pharynx', 'and', 'soft', 'palate.'], ['__', '__', 'very', 'extensible,', 'and', 'that', '__', 'what', 'made', '__', 'astonish', 'its', 'discoverers', '__', 'its', 'bouncing.'], ['They', 'give', '__', 'a', 'quality', '__', 'resilience,', '__', 'spring,', 'while', 'still', 'supporting', 'it.']]

The list of guesses would initially look like this:

[[[''], ['', '', ''], [''], ['', '', '', '', ''], ['', '', '']], [[''], ['', '', ''], [''], ['', '', '', '', ''], ['', '', '']]]

Note there are two sets of guesses, one for you and one for your opponent. The position of your guesses is determined by your PlayerIndex value.

Submitting a guess

To submit a guess you need to give the position of the word and your guess. For example:

myGuess = [0,1,"it"]

would submit the answer "it" to sentence 0 missing/changed word number 1. When the game is in play, your answers, along with your opponents answers, will be displayed in the list of sentences.

Reversing Stones

gamestate

An example of the gamestate JSON

{
'Board': [
[0, -1, -1, -1, -1, -1, -1, 0],
[-1, 0, 1, -1, -1, -1, -1, 0],
[-1, -1, 1, -1, 1, 1, 1, 0],
[-1, -1, 1, 1, 1, 1, 0, -1],
[-1, -1, -1, 0, 1, 0, 0, 0],
[-1, -1, 0, 1, 1, 1, -1, -1],
[-1, -1, -1, -1, -1, -1, -1, -1],
[-1, -1, -1, -1, -1, -1, -1, -1]
],
'Role': 0,
'PossibleMoves': [
[1, 3],
[1, 4],
[1, 5],
[1, 6],
[2, 1],
[2, 3],
[3, 1],
[5, 6],
[6, 2],
[6, 3],
[6, 4],
[6, 5],
[6, 6]
],
'IsMover': True,
'ResponseDeadline': 1543948980212,
'GameStatus': 'RUNNING',
'GameId': 2398557,
'OpponentId': 'housebot-practise'
}

A description of each field in the gamestate

Key

Description

Board

A list of lists representing each row on the board

Role

Whether you are the Dark or Light player. The Dark player moves first.

PossibleMoves

A list of lists containing every valid move that can be made at this point in the game.

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.)

ResponseDeadline

The epoch time, in milliseconds, that a successful move has to be sent and received by to prevent you from timing out

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:

  • -1 - A cell that has not yet had a stone laid on it.

  • 0 - A cell that has a Dark coloured stone on it.

  • 1 - A cell that has a Light coloured stone on it.

Making a valid move

To submit a move you need to return the Row and Column that you want to place a stone on.

{'Row': 4, 'Column': 7}

Sliding Puzzle

gamestate

Example gamestate JSON

{
'Board': [
[5, 8, 7],
[2, 6, 3],
[1, 4, 0]
],
'ResponseDeadline': 1543861424041,
'IsMover': True,
'MyBestSolution': [4, 6, 8, 5, 2, 8, 3, 7, 5, 3, 8, 2, 3, 5, 7, 4, 6, 8, 5, 3, 2, 5, 4, 7, 3, 4, 7, 6, 8, 1, 5, 7, 1, 5, 7, 1, 4, 2, 1, 4, 5, 8],
'OppBestSolution': [3, 7, 8, 5, 2, 1, 4, 3, 7, 6, 3, 7, 6, 8, 5, 3, 8, 5, 3, 2, 1, 4, 7, 8, 5, 6],
'IsLeader': False,
'GameStatus': 'RUNNING',
'GameId': 2398043,
'OpponentId': 'housebot-practise'
}

A description of each field in the gamestate

Key

Description

Board

A list of tile numbers which represents the starting position of the board. The 0 (Zero) is the blank tile which will always be in the bottom right corner. The board will not change throughout the game as you can only submit solutions that solve the puzzle. For more details see "Understanding the Board" in the section below.

ResponseDeadline

The epoch time, in milliseconds at which this game will end

IsMover

A boolean that represents whether you can submit a solution. Always set to True as long as game is running

MyBestSolution

Your current best solution to the puzzle. Each entry in the list is the tile number that you need to move into the blank space in sequence to complete the puzzle. If you have no solution this will be set to "None"

OppBestSolution

Your opponent's best solution to the puzzle. Each entry in the list is the tile number that you need to move into the blank space in sequence to complete the puzzle. If your opponent has no solution this will be set to "None"

IsLeader

A Boolean value indicating whether you are winning.

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 board

The board is a list of the tiles as they appear on the board. For example

[[5, 1, 6], [7, 8, 2], [4, 3, 0]]

would result in the board as displayed below:

Submitting a solution

To submit a solution you need to return a list of steps in calculateMove. Each entry in the list is the tile number that you need to move into the blank space in sequence to complete the puzzle. For example:

return {"Steps":[3, 8, 7, 5, 1, 6, 2, 3, 8, 7, 6, 2, 3, 6, 5, 4, 7, 8]}

Would submit a solution where tile number 3 is the first move into the empty space etc.

When the game is in play the best solution length for each player will be shown and updated on screen. Only at the end of the game will you be shown the animated sequence of the best solution each bot has submitted.

Travelling Salesdrone

gamestate

An example of the gamestate JSON

{
'CityCoords': [
[72, 57],
[15, 55],
[70, 6],
[38, 35],
[50, 6],
[14, 32],
[24, 2],
[57, 79],
[56, 97],
[99, 6]
],
'IsLeading': False,
'MyBestDistance': 470.78493953545126,
'OppBestDistance': 412.4254952473811,
'MyBestSolution': [4, 9, 6, 3, 7, 1, 5, 8, 0, 2],
'OppBestSolution': [8, 7, 0, 4, 9, 2, 5, 3, 6, 1],
'EndTime': 1543863423552,
'GameLength': 20000,
'MyScore': 0,
'OppScore': 0,
'GameStatus': 'RUNNING',
'IsMover': True,
'GameId': 2398062,
'OpponentId': 'housebot-practise'
}

A description of each field in the gamestate

Key

Description

CityCoords

A list of the city co-ordinates as positioned on a 100 by 100 grid. No two cities will share the same spot

IsLeading

A Boolean value indicating whether you are winning

MyBestDistance

A floating point value of the total distance of your best route submitted so far

OppBestDistance

A floating point value of the total distance of your opponents best route submitted so far.

MyBestSolution

The list of city indexes for your current best route eg [2, 6, 3, 8, 9, 5, 4, 7, 1, 0]

OppBestSolution

The list of city indexes for your opponents best route eg [2, 6, 3, 8, 9, 5, 4, 7, 1, 0]

EndTime

The epoch time, in milliseconds at which this game will end

GameLength

The total game length in milliseconds

DealsTotal

Not used in this game. So will always be set to 1.

MyScore

Not used in this game. So will always be set to 0

OppScore

Not used in this game. So will always be set to 0.

GameStatus

A string that will have value "RUNNING" if the game is in progress or a reason the game has ended otherwise

IsMover

A boolean that represents whether you can submit a route. Always set to True as long as game is running.

GameId

An integer representing the unique game id for the current game

OpponentId

A string containing the name of your opponent.

Understanding the map

The list contained in CityCoords are the x and y co-ordinates of all the cities in the game. For example:

([84, 87], [58, 97], [69, 17], [69, 83], [71, 36], [19, 76], [19, 22], [15, 51], [10, 64], [7, 2])

would represent a 10 city game. The top left of the board is position [0, 0].

When the game is in play these will be plotted onto a green map with each city represented as a black dot.

Making a valid move

To submit a route you need to return a list of city indexes in calculateMove. For example

return {"Path":[3,1,2,0,4,5,8,7,6,9]}

Would submit a route around the cities that would suggest cities with the index of 3 and 1 are close together etc.

When the game is in play your route will be plotted onto the map. If your route is coloured yellow you are currently winning the game otherwise it will be shown in red. Your home city will be shown as a white dot with all others coloured in black.

Warehouse Logistics

gamestate

An example of the gamestate JSON

{
'Warehouse': [
[' ', ' ', ' ', ' ', ' ', ' ', ' ', ' ', ' ', ' '],
[' ', ' ', 'F0000', 'F0001', ' ', 'F0002', ' ', ' ', 'F0003', ' '],
[' ', ' ', 'F0007', 'F0006', ' ', 'F0005', ' ', ' ', 'F0004', 'P001'],
[' ', ' ', ' ', ' ', ' ', ' ', ' ', ' ', ' ', ' '],
[' ', 'F0008', 'D000', 'F0009', ' ', 'F0010', 'F0011', 'D001', ' ', ' '],
['P000', 'F0016', 'F0015', 'F0014', ' ', 'F0013', 'D002', 'F0012', ' ', ' '],
[' ', ' ', ' ', ' ', ' ', ' ', ' ', ' ', ' ', ' '],
[' ', 'F0017', ' ', 'F0018', 'D003', ' ', 'F0019', ' ', 'F0020', ' '],
[' ', 'F0025', ' ', 'F0024', 'F0023', ' ', 'F0022', ' ', 'F0021', ' '],