Welcome everyone to a tutorial on Halite III, a game where you compete against other programmers to create artificial intelligences to collect resources.

The overall theme of Halite III is that you have ships (or turtles), that move about to collect "halite" in the ocean. The ships can move in the cardinal directions (north, south, east, or west). You task is to move each ship in a direction per turn. If you move over halite, you will automatically collect it. As your ship fills with halite, you need to drop it off at a shipyard or depot.

You can create more ships with the shipyard, and ships themselves are what you can turn into depots for a cost. As ships move, they also expend halite. If your ship is in close proximity to an enemy, then that ship is "inspired" and will collect halite quicker. If ships collide, they both sink.

Alright, so, when I hear this, I can immediately recognize the crux of this competition boils down to one major thing: pathing, how to best navigate our ships. Our main focus will be on the micro level, on a per-ship basis.

We will of course need to consider other objectives like building more ships, converting ships to depots and trying to surround a smaller number of enemy ships in order to get our ships inspired.

Before we go too far, you will need to get the files required to run locally, or you can run in the browser. The browser is nice, but can make debugging tedious. Once you have a lot of the more basic stuff working, I think browser is more convenient.

Also, there is an embedded tutorial that is worth going through. Beyond this, it can also be helpful to download the files locally, if only just to read the source code. It's all heavily commented and it's a good idea to know what's already available to you to use (methods, functions...etc).

For example, if you download the local code, and go into the hlt directory, check out entity.py, you can see various methods for each of the entities in the game. If you check out game_map.py, you can see all of the methods you can call, such as finding out if a certain position is occupied by a ship or structure, and even a simple navigation function that you'll probably eventually want to modify.

Since this is primarily a pathing issue, our first major task is actually to just figure out where the heck we want to go. Okay, so let's get started! Here's some basic starting code, taken from the tutorial on the Halite website. You can follow along either in the embedded editor, or locally.

# Python 3.6
import hlt  #main halite stuff
from hlt import constants  # halite constants
from hlt.positionals import Direction  # helper for moving
import random  # randomly picking a choice for now.
import logging  # logging stuff to console

game = hlt.Game()  # game object
# Initializes the game
game.ready("Sentdebot")

while True:
    # This loop handles each turn of the game. The game object changes every turn, and you refresh that state by
    game.update_frame()
    # You extract player metadata and the updated map metadata here for convenience.
    me = game.me

    '''comes from game, game comes from before the loop, hlt.Game points to networking, which is where you will 
    find the actual Game class (hlt/networking.py). From here, GameMap is imported from hlt/game_map.py. 
    
    open that file to seee all the things we do with game map.'''
    game_map = game.game_map  # game map data. Recall game is

    # A command queue holds all the commands you will run this turn. You build this list up and submit it at the
    #   end of the turn.
    command_queue = []

    for ship in me.get_ships():
        command_queue.append(
            ship.move(
                random.choice([ Direction.North, Direction.South, Direction.East, Direction.West ])))

    # Send your moves back to the game environment, ending this turn.
    game.end_turn(command_queue)

If we run this code, nothing happens...because we have no ships! Let's make some ships:

    # ship costs 1000, dont make a ship on a ship or they both sink
    if me.halite_amount >= 1000 and not game_map[me.shipyard].is_occupied:
        command_queue.append(me.shipyard.spawn())

Full code:

# Python 3.6
import hlt  #main halite stuff
from hlt import constants  # halite constants
from hlt.positionals import Direction  # helper for moving
import random  # randomly picking a choice for now.
import logging  # logging stuff to console

game = hlt.Game()  # game object
# Initializes the game
game.ready("Sentdebot")

while True:
    # This loop handles each turn of the game. The game object changes every turn, and you refresh that state by
    game.update_frame()
    # You extract player metadata and the updated map metadata here for convenience.
    me = game.me

    '''comes from game, game comes from before the loop, hlt.Game points to networking, which is where you will 
    find the actual Game class (hlt/networking.py). From here, GameMap is imported from hlt/game_map.py. 
    
    open that file to seee all the things we do with game map.'''
    game_map = game.game_map  # game map data. Recall game is

    # A command queue holds all the commands you will run this turn. You build this list up and submit it at the
    #   end of the turn.
    command_queue = []

    for ship in me.get_ships():
        command_queue.append(
            ship.move(
                random.choice([ Direction.North, Direction.South, Direction.East, Direction.West ])))

    # ship costs 1000, dont make a ship on a ship or they both sink
    if me.halite_amount >= 1000 and not game_map[me.shipyard].is_occupied:
        command_queue.append(me.shipyard.spawn())

    # Send your moves back to the game environment, ending this turn.
    game.end_turn(command_queue)

Okay, not horrible, but we're crashing into ourselves and sinking. We also aren't trying to drop off the halite either. In the next tutorial, let's work on fixing these things too.