API Details - V2 (Current)

API Overview

To provide the most uniform API across all languages, the input to the user code of the current map state, and the output from the user code of the players instructions are passed as a (pound/hash) # and comma , separated string of commands, passed through the stdin and stdout functions.

We suggest that new players start with our template bots, or have a look at existing player bots that have their source code public.

Coordinates

The Arena is a 16 x 16 grid of squares and tiles – The X Axis is the horizontal axis, with the left most square starting at 1, with the right most square ending at 16. The Y Axis is the vertical axis, with the bottom most square starting at 1, with the top most square ending at 16.

Within the API coordinates must always be passed in the format of X:Y – Where X is an unsigned integer value from 1 to 16, the colon : separates the X and Y values, and the Y is an unsigned integer value from 1 to 16.

Arena


Bot Input - STDIN

At the start of each turn the bot will receive an input on stdin, which the bot should interpret using the logic described below.

The input from stdin should first be read and split by the users code using the (pound/hash) # character, which should result in three distinct ordered elements - These elements are:

  • Game Data - The first element contains some basic game data
  • Map State - The second element contains the state of the MAP for this turn
  • User Data - The final element contains upto 128 characters of user data
As an example 3,100,2#F-12:6-100,F-13:12-20,E-9:5-100,E-9:12-90#123 would mean 3,100,2 is Game Data, F-12:6-100,F-13:12-20,E-9:5-100,E-9:12-90 is Map State, and 123 is User Data.

These are detailed below:

Game Data

The Game Data element (first) contains a comma , separated ordered list of the following data:

  • Current Turn - This is an unsigned integer of the current turn, ranging from 1 to 100 at present
  • Max Turn - This is an unsigned integer of the final turn, 100 at present
  • Player Id - This is either 1 or 2, showing which player the code is in this arena

The order of this data will remain the same, however it should be assumed that more elements could be appended in the future

As an example 3,100,2 suggests the game is at turn 3 of 100, and we are player 2 in the game.

Map State

The Map State element (second) will identify the current placement of all alive Friendly and Enemy bots within the arena at the start of the turn, and their current health within an integer form ranging from 1 to 100.

The element contains a comma , separated list, which is further separated by hyphens into three sub elements.

  • Friendly / Enemy – The first sub element will be a single uppercase F or E to respectively state if the robot is a friendly or enemy bot. Friendly bots will be ordered first within the input.
  • Coordinates – The second sub element will be a set of coordinates for the robot, within the coordinate format defined above.
  • Health – The third and final sub element is the robot health, which is an unsigned integer ranging from 1 to 100

Arena

As an example F-12:6-100,F-13:12-20,E-9:5-100,E-9:12-90 would be a valid input that states the current arena state is:

  • Friendly at x12 y6 with health 100
  • Friendly at x13 y12 with health 20
  • Enemy at x9 y5 with health 100
  • Enemy at x9 y12 with health 90

User Data

The User Data element (third) is optional, and will be therefore always empty on the first turn.

Within a bots STDOUT output, they are able to provide 128 characters of additional data, if they do so this data will be passed back to the bot on the next turn, within this user data element.

As there is no memory persistence between turns, this could be used to pass persistent data between turns - However please remember that the data is public, as all players can see this within the logs after the game is complete.


Bot Output - STDOUT

The game will await for the user code to complete its execution, and the user code should return a string of instructions via stdout, the instructions must define what interactions the player wishes to perform on the friendly bots during this turn.

The output must be provided within a comma , separated format, which is further separated by hyphens - into two or three sub elements conditional on the instruction requested.

These sub-elements are:

  • Coordinates - The first sub element will be a set of coordinates for the friendly robot, which this instruction relates to. The coordinates are the placement of the bot at the start of the turn before any actions during the turn, that is exactly as provided in the stdin input.
  • Action – The second element will define the action that is to take place, with the possible actions defined below, and detailed further within the game rules.
    • Attack - Encoded as A (Requires a direction element)
    • Move - Encoded as M (Requires a direction element)
    • Defend - Encoded as D
    • Self Destruct - Encoded as S
  • Direction – Some actions (such as move or attack) are directional, therefore where a direction is required the third element will be included to provide this detail, the optional directions are:
    • North / Up – Encoded as N or U
    • East / Right – Encoded as E or R
    • South / Down – Encoded as S or D
    • West / Left – Encoded as W or L

Arena

As an example 12:7-A-S,10:5-M-E,10:12-D would be a valid output that requests:

  • Friendly at x12 y7 should attack, in a south direction, therefore x12 y6
  • Friendly at x10 y5 should move, in an east direction, tehrfore x11 y5
  • Friendly at x10 y12 should defend

If you do not provide an instruction for a bot, then we will place the bot into a Defend state for the turn

User Data

Optionally if a robot wishes to pass up to 128 characters of user data to itself in the next turn, then it can do so by appending a (pound/hash) # character to its output, followed by it's chosen user data characters.

On the next turn this data will be passed back to the robot on stdin, as defined above.

As an example, the instructions 12:7-A-S,10:5-M-E,10:12-D#A1-B2-C2-N6 would cause A1-B2-C2-N6 to be stored, and passed back to the robot on the next turn.

Data is only stored for one turn, so your code must always return what user data you wish to pass into the next turn

❤️ Feedback