Programmer's Reference

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.
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',

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

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


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

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

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

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

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

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

Programmer's Reference

Introduction

Battleships

gamestate

Understanding the boards

Making a valid move

Ship Placement Move

Ship Hunting Move

​

Helper Functions

Jargon

Blurry Words

gamestate

Checkers

gamestate

Understanding the boards

Making a valid move

Dominoes

gamestate

Understanding the board

Making a Valid Move

Go

gamestate

Understanding The Board

Making A Valid Move

Microsoft Match Game

gamestate

Making a valid move

Mastermind

gamestate

Making a valid move

Submit your hidden peg sequence

Submit a Guess

Understanding the Comparison Result

Noughts & Crosses

gamestate

Understanding The Boards

Making A Valid Move

Predictive Text

gamestate