Robust Turtle API

This is an unofficial API. This means that you have to install it manually.
This API extends on the original turtle API and makes it more robust. It also strives to make coding a turtle easier.
When traveling, for example, it will not get stopped by mobs, players, sand, or any other block.

Installation

Install globally on all Turtles:

• Create and install a new resource pack on the client (if playing singleplayer) or the server (if playing multiplayer).
• Download the API and save it in the 'assets/computercraft/lua/rom/apis/turtle' directory inside the resource pack.
• The name of the file will determine the name of the API (If you save it as 't' you'd call the 'forward()' function like so: t.forward()).
• The API will automatically be loaded for every Turtle.

Install only on one specific Turtle:

• Open the computer you want to download the API into and type: 'pastebin get 0TnEBf2P t' (without the quotes) to download and save the API as 't'.
• Before using the API you'll have to load it: os.loadAPI("t").

Usage

A lot of the functions do the same as the default turtle API, except with additional checks. There are also some functions that combine default functions for ease of use. E.g. turnAround() turns right twice.
Most of the function names are the same, but instead of writing "turtle." in front, you now write "t.".

Digging
These will dig as long as there is a block in the way. So if sand falls down, it will dig as long as necessary.

• t.dig()
• t.digUp()
• t.digDown()

Traveling
These will not be stopped by blocks or mobs.
[amount] is optional, you can leave it out. It is the amount of blocks to travel. If left out these will travel 1 block.

• t.forward([amount])
• t.up([amount])
• t.down([amount])
• t.back([amount])

Placing blocks
Here, 'block' is a number between 1 and 16. It combines selecting and placing.
I highly recommend adding e.g. "stoneBrick = 1" at the beginning of the code. This way you can later easily see which block must go in which slot. Example: "t.place(stoneBrick)".
If there is another block in the way, it will break it, unless it is the same type of block.

• t.place(block)
• t.placeUp(block)
• t.placeDown(block)
• t.placeRight(block)
• t.placeLeft(block)
• t.placeBack(block)

The following function places a row of blocks:

• t.placeRow(placeDir, block, travelDir, length)
  • travelDir is the most logical one. It is the direction the turtle travels to. Possible directions: "forward","up","down","right","left","back".
  • placeDir is a bit more difficult to understand. placeDir is the direction to place the block in. The turtle travels in one direction, but it cannot place a block in that direction (it can, but it will get dug up again). This means that the place direction must be another direction as the travel direction. The possible directions are the same as travelDir.
  • length is the amount of blocks to travel.
  • Example: t.placeRow(up, marble, forward, 15)

If any of these run out of their resource, the API will write a message and waits for any text input to continue.
This way you can refill and write something (anything) to continue the program.

Turning
This function simply turns right twice. If you really want, you can change it to turn left twice ;).

• t.turnAround()

These are simply a shorter way to write turtle.turnLeft() and turtle.turnRight().

• t.right()
• t.left()

These simply turn left or right, and move forward an amount.
[amount] is optional, and is the amount of blocks to travel forward. If left out these will travel 1 block.

• t.goRight([amount])
• t.goLeft([amount])

These are the same as the previous functions, except at the end they turn back again.

• t.strafeRight([amount])
• t.strafeLeft([amount])

Code

Download: Robust Turtle API
Save it as 't', without ".txt".

--Robust Turtle API by SpeedR

--Digging with gravel/sand detection
function dig()
  local tries = 0
  while turtle.detect() do
    turtle.dig()
    sleep(0.4)
    tries = tries + 1
    if tries>500 then
      print("Error: dug for too long.")
      return false
    end
  end
  return true
end

function digUp()
  local tries = 0
  while turtle.detectUp() do
    turtle.digUp()
    sleep(0.4)
    tries = tries + 1
    if tries>500 then
      print("Error: dug up for too long.")
      return false
    end
  end
  return true
end

function digDown()
  local tries = 0
  while turtle.detectDown() do
    turtle.digDown()
    sleep(0.4)
    tries = tries + 1
    if tries>500 then
      print("Error: dug down for too long.")
      return false
    end
  end
  return true
end


--Traveling: Goes in the direction no matter what (almost)
--Will not be stopped by blocks or mobs
function forward(l)
  l=l or 1
  for i=1,l do
    local tries = 0
    while turtle.forward() ~= true do
      turtle.dig()
      turtle.attack()
      sleep(0.2)
      tries = tries + 1
      if tries>500 then
        print("Error: can't move forward.")
        return false
      end
    end
  end
  return true
end

function up(l)
  l=l or 1
  for i=1,l do
    local tries = 0
    while turtle.up() ~= true do
      turtle.digUp()
      turtle.attackUp()
      sleep(0.2)
      tries = tries + 1
      if tries>500 then
        print("Error: can't move up.")
        return false
      end
    end
  end
  return true
end

function down(l)
  l=l or 1
  for i=1,l do
    local tries = 0
    while turtle.down() ~= true do
      turtle.digDown()
      turtle.attackDown()
      sleep(0.2)
      tries = tries + 1
      if tries>500 then
        print("Error: can't move down.")
        return false
      end
    end
  end
  return true
end

function back(l)
  l=l or 1
  for i=1,l do
    if turtle.back() ~= true then
      turnAround()
      forward()
      turnAround()
    end
  end
end


--Place blocks
--Does not place when there's already the right block.
function place(block)
  turtle.select(block)
  if turtle.compare()==false then
    if turtle.getItemCount(block)==0 then
      outOfResource(block)
    end
    dig()
    turtle.place()
  end
end

function placeUp(block)
  turtle.select(block)
  if turtle.compareUp()==false then
    if turtle.getItemCount(block)==0 then
      outOfResource(block)
    end
    digUp()
    turtle.placeUp()
  end
end

function placeDown(block)
  turtle.select(block)
  if turtle.compareDown()==false then
    if turtle.getItemCount(block)==0 then
      outOfResource(block)
    end
    digDown()
    turtle.placeDown()
  end
end

local function outOfResource()
  print("Ran out of a resource. Block: ",block , ".")
  print("Refill, then say something to proceed.")
  read()
end

function placeRight(block)
  turtle.turnRight()
  place(block)
  turtle.turnLeft()
end

function placeLeft(block)
  turtle.turnLeft()
  place(block)
  turtle.turnRight()
end

function placeBack(block)
  turnAround()
  place(block)
  turnAround()
end

--place row     e.g. placeRow(up, marble, forward, 15)
function placeRow(placeDir, block, travelDir, l) 
  l=l or 1
  for i=1,l do
    if placeDir == "forward" then
      place(block)
    elseif placeDir == "up" then
      placeUp(block)
    elseif placeDir == "down" then
      placeDown(block)
    elseif placeDir == "right" then
      placeRight(block)
    elseif placeDir == "left" then
      placeLeft(block)
    elseif placeDir == "back" then
      placeBack(block)
    else
      print('"', placeDir, '" is not a valid direction!')
      return false
    end
    if travelDir == "forward" then
      forward()
    elseif travelDir == "up" then
      up()
    elseif travelDir == "down" then
      down()
    elseif travelDir == "right" then
      strafeRight()
    elseif travelDir == "left" then
      strafeLeft()
    elseif travelDir == "back" then
      back()
    else
      print('"', travelDir, '" is not a valid direction!')
      return false
    end
  end
  return true
end


--Turning
function turnAround()
  turtle.turnRight()
  turtle.turnRight()
end

function right()
  turtle.turnRight()
end

function left()
  turtle.turnLeft()
end

function goRight(l)
  l=l or 1
  turtle.turnRight()
  forward(l)
end

function goLeft(l)
  l=l or 1
  turtle.turnLeft()
  forward(l)
end

function strafeRight(l)
  l=l or 1
  goRight(l)
  turtle.turnLeft()
end

function strafeLeft(l)
  l=l or 1
  goLeft(l)
  turtle.turnRight()
end