Difference between revisions of "Robust Turtle API"

Revision as of 03:11, 14 April 2013

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 strives to make coding a turtle easier.
When traveling for example, it will not get stopped by mobs, players, or any block. Not even sand that comes falling down.

Installation

• Go to minecraft/mods/computercraft.zip/lua/rom/apis/turtle (if you are running on a server, only the server needs the file).
• Save the code beneath as 't', so that you can easily call every function in-game, e.g. "t.forward()".
• Add the file to the folder.

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. 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)".

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

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.

The following is a special function. It is an extended version of the place functions. It places a row of blocks:

• t.placeExt(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. Possible directions are the same as travelDir.
  • length is the amount of blocks to travel.
  • Example: t.placeExt(up, marble, forward, 15)

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

--Digging with gravel/sand detection
function dig()
  while turtle.detect() do
    turtle.dig()
    sleep(0.4)
  end
end

function digUp()
  while turtle.detectUp() do
    turtle.digUp()
    sleep(0.4)
  end
end

function digDown()
  while turtle.detectDown() do
    turtle.digDown()
    sleep(0.4)
  end
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 extended     e.g. placeExt(up, marble, forward, 15)
function placeExt(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