A basic template for a [trAInsported](http://trainsportedgame.no-ip.org/) AI containing the documentation.

trAIn_template.lua

--[[
    Name:
    Author:
    Version:
    Description:
]]--

--[[
    This event is called, at the beginning of the round. The current map is
    passed to it, so you can analize it, get it ready for pathfinding and search
    it for important junctions, Hotspots, shortest paths etc.

    Arguments:
     - map: A 2D representation of the current map. "map" has a field map.width
            and a field map.height to check the size of the map. It also holds
            information about what's on the map, which is stored by x and y
            coordinates. For example, to see what's at the position x=3, y=5,
            you only have to check map[3][5].
            A map field can be filled with:
                - "C" (Connected Rail)
                - "H" (House)
                - "S" (Hotspot)
     - money: The amount of money that you currently have. You can use this to
              check how many trains you may buy (one train costs 25 credits).
]]--
function ai.init(map, money)
end

--[[
    Called when the train you bought using buyTrain has successfully been
    created.  

    Arguments:
     - train: A Lua table representing the train.See ai.chooseDirection for
              details.
]]--
function ai.newTrain(train)
end

--[[
    Called just before a train enters a junction. This function is essential: It
    lets your train tell the game where it wants to go. If this function returns
    a valid direction (N, E, S or W) and the direction is not blocked by another
    train, the train will continue in that direction.  

    Arguments:
     - train: a Lua table representing the train. It has the fields:
        - train.ID (an ID representing the train - number)
        - train.name (the name of the train - string)
        - train.x (x-position of the tile the train is on - number)
        - train.y (y-position of the tile the train is on - number)
        - train.dir (the direction the train is going in - "N", "S", "E" or "W")
        - train.passenger (table representing passenger who's currently on the
                          train, if any - holds the passengers name, destX and
                          destY. See ai.foundPassengers for more details.)
        - (**NOTE:** The trains' .x and .y fields are the coordinates of the
          tile it's coming from. So in this function, there's also a .nextX and
          .nextY field to describe the tile of the junction the train is moving
          to. Not all functions that get a train have these fields, usually just
          .x and .y do the job.)
     - possibleDirections: a Lua table showing the directions which the train
                           can choose from. One of these directions should be
                           returned by the function, to make the train go that
                           way. The table's indieces are the direction
                           ("N","S","E","W") and if the value at the index is
                           true, then this direction is one that the train can
                           move in.

    Returns:
     - The function should return a string holding one of the directions which
       are stored in possibleDirections ("N", "S", "E", "W" are the possible
       values). If a wrong value is returned, or nothing is returned then the
       game will automatically try the directions in the following order:
       N, S, E, W
]]--
function ai.chooseDirection(train, possibleDirections)
end

--[[
    Called after a train was blocked by another train and can't move in that
    direction. By returning the prevDirection, you can keep trying to go in the
    same direction. However, you should not try to keep moving in the same
    direction forever, because then trains could block each other for the rest
    of the match.

    Arguments:
     - train: same as above (see ai.chooseDirection)
     - possibleDirections: a Lua table showing the directions which the train
       can choose from. One of these directions should be returned by the
       function, to make the train go that way. The table's indieces are the
       direction ("N","S","E","W") and if the value at the index is true, then
       this direction is one that the train can move in.
     - prevDirection: the direction that the train previously tried to move in,
       but was blocked.

    Returns:
     - The function should return a string holding one of the directions which
       are stored in possibleDirections ("N", "S", "E", "W" are the possible
       values). If a wrong value is returned, or nothing is returned then the
       game will automatically try the directions in the following order:
       N, S, E, W
]]--
function ai.blocked(train, possibleDirections, prevDirection)
end

--[[
    This function is called when a train arrives at a position where passengers
    are waiting to be picked up. If one of the passengers in the list is
    returned, then this passenger is picked up (but only if the train does not
    have a passenger at the moment). If you want to pick up a passenger but
    you're already trainsporting another passenger, you can drop the current
    passenger using the function 'dropPassenger'.

    Arguments:
     - train: the train which has arrived at a position where passengers are
       waiting. Same as above (see ai.chooseDirection)
     - passengers: List of passengers which are at this position. Each passenger
       is a table containing:
        - name: Name of the passenger
        - destX: Destination of the passenger (X-coordinate)
        - destY: Destination of the passenger (Y-coordinate)

    Returns:
     - Passenger: The passenger in the list who is to be picked up.
                  (i.e. passengers[1] or passengers[2])
]]--
function ai.foundPassengers(train, passengers)
end

--[[
    This function is called when a train which is carrying a passenger arrives
    at the position where the passenger wants to go. This way, you can drop off
    the passenger by calling 'dropPassenger'.

    Arguments:
     - train: same as above (see ai.chooseDirection)
]]--
function ai.foundDestination(train)
end

--[[
    Whenever the player earns money, the game checks if the player now has
    enough money to buy a new train. If that is the case, then this function is
    called so that the player can decide whether to buy a new train by calling
    buyTrain() and if so, where to place it.

    Arguments:
     - money: The amount of money you now have.
]]--
function ai.enoughMoney(money)
end

--[[
    Will be called whenever a new passenger spawns on the map, or if a passenger
    has been dropped off at a place that was not his destination.

    Arguments:
     - name: Name of the passenger. If the passenger is a VIP, then "[VIP]" is
             appended to his name.
     - x, y: The x and y positions of the tile on which the passenger is
             standing.
     - destX, destY: The x and y position of the tile to which the passenger
                     would like to be transported. As soon as you drop him/her
                     of at this position, you will get paid.
     - vipTime: If the passenger is a VIP, then this is the time in seconds
                until he stops being a vip. Each VIP has a vipTime that's
                dependant on the distance they want to travel. **Careful**, if
                the passenger is not a VIP then this value will be nil! So
                always check: "if vipTime then ..." before you do anything with
                it. If you want to work with the vipTime, os.time() migth be a
                good function to check out - this way you can get the time
                passed between two times.
]]--
function ai.newPassenger(name, x, y, destX, destY, vipTime)
end

--[[
    Will be called whenever a train of another player has taken a passenger
    aboard. You can use this function to make sure your trains no longer try to
    go to that passenger, if that was their plan.  
    Note: This function is NOT called when one of your own trains takes a
    passenger aboard!

    Arguments:
     - train: the train which has taken the passenger in.
              (Same as for chooseDirection)
     - passenger: name of passenger who has boarded a train.
]]--
function ai.passengerBoarded(train, passenger)
end