tAddOn.lua

-- This is an addon API for ComputerCraft turtles.
local pos = vector.new(0, 0, 0)
local heading = 0

-- Saves the turtle's current location and heading to a file.
local saveLocation = function()
  local f = fs.open("/API/TurtleLocation.txt", "w")
  f.writeLine(pos.x)
  f.writeLine(pos.y)
  f.writeLine(pos.z)
  f.write(heading)
  f.close()
end

-- Returns true if a gps location could be found, false if not.
local getGPS = function(dir)
  local newPos = vector.new(gps.locate(0.5))
  if newPos then
    if newPos.z < pos.z then
      if dir == "forward" then heading = 0
      elseif dir == "back" then heading = 2 end
    elseif newPos.x > pos.x then
      if dir == "forward" then heading = 1
      elseif dir == "back" then heading = 3 end
    elseif newPos.z > pos.z then
      if dir == "forward" then heading = 2
      elseif dir == "back" then heading = 0 end
    elseif newPos.x < pos.x then
      if dir == "forward" then heading = 3
      elseif dir == "back" then heading = 1 end
    end
    pos = newPos
    return true
  end
  return false
end

-- Loads the current position from the saved file, if it is present.
-- Then attempts to verify the location through gps.
if fs.exists("/API/TurtleLocation.txt") then
  local f = fs.open("/API/TurtleLocation.txt", "r")
  pos = vector.new(tonumber(f.readLine()), tonumber(f.readLine()), tonumber(f.readLine()))
  heading = tonumber(f.readLine())
  f.close()
end
getGPS()

-- Returns the current location heading.
-- Pass "x", "y" or "z" for specific dimensional values.
-- Pass "h" for heading.
-- Pass nothing for all values.
tGetPos = function(vect)
  local headings = {
    [0] = "North",
    [1] = "East",
    [2] = "South",
    [3] = "West"
  }
  getGPS()
  if vect == nil then
    return pos.x, pos.y, pos.z, headings[heading]
  elseif vect == 'h' then
    return headings[heading]
  else
    return pos[vect]
  end
end

-- Attempts to refuel the only if the turtle is out of fuel.
-- Pass a number to specify the amount of items to use, up to 64.
-- Default is number of items used is 1.
tRefuel = function(a)
  a = math.min(a or 1, 64)
  local hasFuel = true
  while turtle.getFuelLevel() == 0 do
    for i = 1, 16 do
      turtle.select(i)
      if turtle.refuel(a) then return turtle.getFuelLevel() end
    end
    if hasFuel then print("Out of Fuel.") end
  end
end

-- This is the engine for the turtle's movement.
-- Turtle will keep trying to move until it is able to successfuly move.
-- Returns the current position after movement.
local move = function(n, dir, dig)
  n = n or 1
  local moves = {
    up = vector.new(0, 1, 0),
    down = vector.new(0, -1, 0),
    forward = {
      [0] = vector.new(0, 0, -1),
      [1] = vector.new(-1, 0, 0),
      [2] = vector.new(0, 0, 1),
      [3] = vector.new(1, 0, 0)
    },
    back = {
      [0] = vector.new(0, 0, 1),
      [1] = vector.new(1, 0, 0),
      [2] = vector.new(0, 0, -1),
      [3] = vector.new(-1, 0, 0)
    },
    turnLeft = -1,
    turnRight = 1
  }

  for i = 1, n do
    repeat
      if dig ~= nil then turtle[dig]() end
      tRefuel()
    until turtle[dir]()

    if dir == "turnLeft" or dir == "turnRight" then
      heading = heading + moves[dir]
      heading = (heading + 4) % 4
    elseif not getGPS(dir) then
      if dir == "forward" or dir == "back" then pos = pos + moves[dir][pos.w]
      else pos = pos + moves[dir] end
    end
    saveLocation()
  end
  return tGetPos()
end

-- Turns the turtle toward a specific cardinal direction.
-- GPS is required for accuracy.
local cardinalTurn = function(dir)
  while heading ~= dir do
    if (heading-dir+2)%4 < 3 then
      move(1, "turnRight")
    else
      move(1, "turnLeft")
    end
  end
  return tGetPos()
end

-- This is the controller for the turtle's movement.
tMove = {
  up = function(n) return move(n, "up", "digUp") end,
  down = function(n) return move(n, "down", "digDown") end,
  forward = function(n) return move(n, "forward", "dig") end,
  back = function(n) return move(n, "back") end,
  left = function(n) return move(n, "turnLeft") end,
  right = function(n) return move(n, "turnRight") end,
  north = function() return cardinalTurn(0) end,
  east = function() return cardinalTurn(1) end,
  south = function() return cardinalTurn(2) end,
  west = function() return cardinalTurn(3) end
}

--[[ Changelog
2023/04/22:
• Fixed bug causing location data to not be loaded from the file correctly.
• Shortened GPS timeout so the program doesn't stall.

2023/04/21:
• Added four new methods to 'tMove': 'north', 'east', 'south' and 'west'. Use
  these methods to turn the turtle toward the cardinal directions. GPS is
  required for accuracy.

2023/04/20:
• Turtle's position is now obtained from a GPS satellite.
• If GPS position can't be obtained, it retrieves it's position from a
  previously saved file.
• If no such file is present, its default location and heading are 0, 0, 0, 0.
• tRefuel will print "Out of fuel." if the current fuel level is 0 and it was
  unable to find an item in its inventory to refuel.
• Changed turtle position to a 3D vector and removed the need for
  'LibAppend.lua'.
• Heading value has been moved to its own variable.

2023/04/19:
• 'LibAppend.lua' is now required for 4D vectors for turtle position and heading.
• 'tRefuel' returns current fuel level after refueling.
• 'tMove' returns turtle's current position after moving.
]]