Writing Your Own Starter Package

API Design

Please try to generally adhere to the API used in the Java, Python, and C++. This is as follows:

  • Global Functions
    • getInit
    • sendInit
    • getFrame
    • sendFrame
  • Classes/Structs
    • Map
    • Location
    • Site
    • Move
  • Constants
    • the directions - NORTH, EAST, SOUTH, WEST, STILL

Of course, if changes to this API will make the starter package fit more nicely into your language, feel free to make them. A Java API will not translate directly into Lisp nicely.

Networking Overview

Bots communicate with the environment via stdin and stdout using series of space separated integers. There are two stages of communication - initialization and turn formats, and these are detailed below.


At the beginning of the game, bot is sent the following, with each item newline-terminated:

  1. A single integer representing their own tag within the game.
  2. Two integers representing the WIDTH and HEIGHT of the map.
  3. The production map.
  4. The initial game map.

Every bot is expected to respond with a string representing their name (newline-terminated) within fifteen seconds.


Every turn, every bot is sent the the present game map (newline-terminated). Every bot is expected to respond with a set of moves (newline-terminated) within one second.

Networking Specifics

Input Game Map Format

The state of the map (including owner and strength values, but excluding production values) is sent in the following way:

  • One integer, COUNTER, representing the number of tiles with the same owner consecutively.
  • One integer, OWNER, representing the owner of the tiles COUNTER encodes.

The above repeats until the COUNTER total is equal to the area of the map. It fills in the map from row 1 to row HEIGHT and within a row from column 1 to column WIDTH. Please be aware that the top row is the first row, as Halite uses screen-type coordinates.

This is then followed by WIDTH * HEIGHT integers, representing the strength values of the tiles in the map. It fills in the map in the same way owner values fill in the map.

Consider the following 3x3 map as an example (where [O=x,S=y] represents a tile owned by player x with strength y):

[O=0,S=122] [O=1,S=25] [O=1,S=18]
[O=0, S=13] [O=0,S=45] [O=1,S=22]
[O=2,S=255] [O=2,S=85] [O=0, S=0]

This map would be encoded using the following string:

1 0 2 1 2 0 1 1 2 2 1 0 122 25 18 13 45 22 255 85 0

Input Production Format

The production values of the map are sent using WIDTH * HEIGHT integers which fill in the production values of the map from row 1 to row HEIGHT and within a row from column 1 to column WIDTH Consider the following 3x3 production map as an example (where [x] represents a tile with x production):


This map would be encoded using the following string:

2 3 4 1 2 3 0 1 2

Output Move Set Format

Bots should send their moves as a list of integers in sets of 3. In each set, every first integer is the x location (starting at 0) of the site the bot desires to move, every second integer is the y location (starting at 0) of the site the bot desires to move, and every third integer is the direction the bot wishes to move the site in. The order of the sets does not matter.

Valid directions include:

  • 0 - STILL
  • 1 - NORTH
  • 2 - EAST
  • 3 - SOUTH
  • 4 - WEST

Please note that these directions correspond most directly to screen coordinates; that is, NORTH decrements the y value of the site by 1 and SOUTH increments the value by 1. Attempts to move nonexistent or enemy pieces or to move pieces in nonexistent directions will be ignored. If multiple separate moves are issued for the same piece, the lower direction value will be preferred.

Consider the following case as an example:
I wish to order a piece located at (3, 4) to move EAST, a piece located at (4, 0) to remain STILL, and a piece located at (4, 5) to move NORTH.
This would be encoded with the following string:

3 4 2 4 0 0 4 5 1

Note: if you would like an alternate way of communicating with the environment, please see a future post on the forums for how to communicate with the environment over sockets instead of pipes if you need to use a debugger or similar to work on your bot.

Submitting Your New Starter Package

Fork our repo, place your starter package in the airesources/ folder, and send us a pull request! If we accept your PR, your starter package will be added to the site.
Note: please include the runGame.sh and runGame.bat scripts (each run a 30 by 30 game between MyBot and RandomBot) and the MyBot and RandomBot files (both just random bots).

Terms of Service | Privacy Policy