Ants Starter Pack Guide

The objective of the starter bots should be to be as helpful as possible for beginners who may not be able to do their own rewrite. It should also showcase good readable design and best practices for the language.

Valid directions are spaces that not water. (LAND, HILL, DEAD, ANT, FOOD) Note: food will block movement, so it is not passable, but the starter bots should still attempt to move there.
Update: For the python starter bot:

passable means not WATER and ants might have the ability to move there at some point, if not this turn.

unoccupied means LAND, HILL or DEAD and ants can move there this turn.

occupied means ANT, FOOD or WATER and ants can not move there this turn.
Please attempt to stick to these naming conventions.

Don't attempt to avoid collision with ants. This will be part of the strategy guide and an exercise for the programmer.

Attempt to separate this logic from the core functionality and helper functions using the best technique for the language. (OOP, library, separate files) The game loop can be included in the bot file, in which case attempt to separate the other core functionality out of it.

Core Functionality

State Tracking:
Internal matrix representation of the map in row, col format. Ability to remember seen water. Everything is land unless told otherwise. Anything with ants or food will be assumed to be land when updating. All coordinates or vectors should be kept in row, col format.
Update: Hills are added to the game. An ant can be located on a hill. The matrix can store a bit field/object or not store hills. Hills turn to land after being razed.

Game Loop:
Read and cache bot input until a 'ready', 'go', or 'end' is received, then call the update function. The Update, Issue Order and Finish Turn functions can be rolled into the game loop if clearly commented, unless the game loop is part of the starter bot logic. (see above)

Update:
Parse the bot input and update the internal state of the game. Should clear ants and food before each turn and only add back what is given by the engine.

Issue Order:
Function to receive an order in the languages preferred data structure and translate it to a string for bot output. Don't update the internal state. This will be part of the strategy guide and an exercise for the programmer.

Finish Turn:
Function to send a 'go' string to the game engine.

Game Variables:
Be able to add a getter function, object property, or the language's equivilant to allow to allow the bot to reference the game variables passed in by the engine.

Helper Functions (Optional)

My Hills:
Function to return an iterable list of hills that belong to the bot.

Enemy Hills:
Function to return an iterable list of hills that do not belong to the bot.

My Ants:
Function to return an iterable list of ants that belong to the bot.

Enemy Ants:
Function to return an iterable list of ants that do not belong to the bot.

Food:
Function to return an iterable list of food on the map.

Distance:
Provide a function to determine the shortest distance between 2 points on a torus.

Direction:
Provide a function to determine the 1 or 2 orthogonal directions from one point to another on a torus.

Visible:
Provide a function to determine if a square can be seen by the bot.

Passable:
Update: Provide a function to determine if an ant could be ordered into a square if vacant.

Unoccupied:
Update: Provide a function to determine if an ant can be ordered into a square successfully this turn.

Time Remaining:
Provide a function to return the number of milliseconds left since the last 'go' was received from the game engine.

Please keep the functions named as given, using the naming conventions of the language. (issue_order, issueOrder) This will allow for contestants to be able to discuss and help others with multiple languages with some consistency.