Turtle API

From ComputerCraft
Jump to navigation Jump to search

The turtle API is exclusive to turtles and advanced turtles.


FunctionFunctionturtle.attack
Attacks the entity in direction and range
Syntax turtle.attack()
Returns bool didAttack
Part of CC:Tweaked (source)
API turtle
ExampleExampleCheck for hit
See if it was able to hit the entity it targeted
Code 
local didHit = turtle.attack()
print(didHit)
Output 
false
1


FunctionFunctionturtle.attackDown
Attacks the entity under the turtle
Syntax turtle.attackDown()
Returns bool didAttack
Part of CC:Tweaked (source)
API turtle
ExampleExampleCheck for hit
See if it was able to hit the entity it targeted
Code 
local didHit = turtle.attack()
print(didHit)
Output 
false


FunctionFunctionturtle.attackUp
Attacks the entity over the turtle
Syntax turtle.attackUp()
Returns bool didAttack
Part of CC:Tweaked (source)
API turtle
ExampleExampleCheck for hit
See if it was able to hit the entity it targeted
Code 
local didHit = turtle.attack()
print(didHit)
Output 
false


FunctionFunctionturtle.back
When called, tries to move the turtle backwards 1 block in the direction it is facing. The function will return false if the destination is obstructed or protected, or if the turtle is out of fuel. Note Note: This function call consumes fuel, if it is enabled in the mod configuration. It will not work if the turtle has no fuel.
Syntax turtle.back()
Returns boolean success [, string error ]
Part of CC:Tweaked (source)
API turtle
ExampleExampleMoving a turtle
Tries to move the turtle 3 blocks backward, and tells the player if this succeeded.
Code 
-- first we set these variables
local blocksSucceeded = 0
local blocksToMove = 3

-- then we initiate a 'for loop'. The for loop will execute the code in it's body multiple times, from 1 to 'blocksToMove' in this case, which we set to 3.
for attempt = 1, blocksToMove do
  local success, error = turtle.back()
  if not success then -- what to do if the move failed
    break -- break will stop the 'for loop' from continuing
  else -- what to do if the move succeeded
    blocksSucceeded = blocksSucceeded + 1
  end
end

-- now we're going to print the results to screen.
if blocksToMove == blocksSucceeded then
  print("Sucessfully moved backward by", blocksToMove, "blocks!")
else
  print("Did not move the target of", blocksToMove, ", but moved", blocksSucceeded, "blocks instead!")
end

Turtle.compare Turtle.compareDown Turtle.compareTo Turtle.compareUp Turtle.craft

FunctionFunctionturtle.detect
When called, will return true if the block in front of the turtle is anything that is not air or liquid.
Syntax turtle.detect()
Returns boolean result
Part of CC:Tweaked (source)
API turtle
ExampleExampleDetecting blocks
Detect if there is a block in front of the turtle.
Code 
local result = turtle.detect()
if result then
  print("There is a block in front of the turtle!")
else
  print("There is no block in front of the turtle, only air or a liquid.")
end
Output 
There is a block in front of the turtle!


FunctionFunctionturtle.detectDown
When called, will return true if the block below the turtle is anything that is not air or liquid.
Syntax turtle.detectDown()
Returns boolean result
Part of CC:Tweaked (source)
API turtle
ExampleExampleDetecting blocks
Detect if there is a block below the turtle.
Code 
local result = turtle.detectDown()
if result then
  print("There is a block below the turtle!")
else
  print("There is no block below the turtle, only air or a liquid.")
end
Output 
There is a block below the turtle!


FunctionFunctionturtle.detectUp
When called, will return true if the block above the turtle is anything that is not air or liquid.
Syntax turtle.detectUp()
Returns boolean result
Part of CC:Tweaked (source)
API turtle
ExampleExampleDetecting blocks
Detect if there is a block above the turtle.
Code 
local result = turtle.detectUp()
if result then
  print("There is a block above the turtle!")
else
  print("There is no block above the turtle, only air or a liquid.")
end
Output 
There is a block above the turtle!

Turtle.dig Turtle.digDown Turtle.digUp

FunctionFunctionturtle.down
When called, tries to move the turtle down 1 block. The function will return false if the destination is obstructed or protected, or if the turtle is out of fuel. Note Note: This function call consumes fuel, if it is enabled in the mod configuration. It will not work if the turtle has no fuel.
Syntax turtle.down()
Returns boolean success [, string error ]
Part of CC:Tweaked (source)
API turtle
ExampleExampleMoving a turtle
Tries to move the turtle 3 blocks down, and tells the player if this succeeded.
Code 
-- first we set these variables
local blocksSucceeded = 0
local blocksToMove = 3

-- then we initiate a 'for loop'. The for loop will execute the code in it's body multiple times, from 1 to 'blocksToMove' in this case, which we set to 3.
for attempt = 1, blocksToMove do
  local success, error = turtle.down()
  if not success then -- what to do if the move failed
    break -- break will stop the 'for loop' from continuing
  else -- what to do if the move succeeded
    blocksSucceeded = blocksSucceeded + 1
  end
end

-- now we're going to print the results to screen.
if blocksToMove == blocksSucceeded then
  print("Sucessfully moved down by", blocksToMove, "blocks!")
else
  print("Did not move the target of", blocksToMove, ", but moved", blocksSucceeded, "blocks instead!")
end

Turtle.drop Turtle.dropDown Turtle.dropUp Turtle.equipLeft Turtle.equipRight

FunctionFunctionturtle.forward
When called, tries to move the turtle forward 1 block in the direction it is facing. The function will return false if the destination is obstructed or protected, or if the turtle is out of fuel. Note Note: This function call consumes fuel, if it is enabled in the mod configuration. It will not work if the turtle has no fuel.
Syntax turtle.forward()
Returns boolean success [, string error ]
Part of CC:Tweaked (source)
API turtle
ExampleExampleMoving a turtle
Tries to move the turtle 3 blocks forward, and tells the player if this succeeded.
Code 
-- first we set these variables
local blocksSucceeded = 0
local blocksToMove = 3

-- then we initiate a 'for loop'. The for loop will execute the code in it's body multiple times, from 1 to 'blocksToMove' in this case, which we set to 3.
for attempt = 1, blocksToMove do
  local success, error = turtle.forward()
  if not success then -- what to do if the move failed
    break -- break will stop the 'for loop' from continuing
  else -- what to do if the move succeeded
    blocksSucceeded = blocksSucceeded + 1
  end
end

-- now we're going to print the results to screen.
if blocksToMove == blocksSucceeded then
  print("Sucessfully moved forward by", blocksToMove, "blocks!")
else
  print("Did not move the target of", blocksToMove, ", but moved", blocksSucceeded, "blocks instead!")
end


FunctionFunctionturtle.getFuelLevel
Returns a number representing the current amount of fuel (block moves) the turtle currently holds.
Syntax turtle.getFuelLevel()
Returns number fuel
Part of CC:Tweaked
API turtle
ExampleExampleGet fuel level
Get the amount of blocks a turtle can still move.
Code 
print("We can still move", turtle.getFuelLevel(), "blocks before we run out of fuel!")
Output 
We can still move 9802 blocks before we run out of fuel!
ExampleExampleGet fuel level in percentage
Get the fuel level of a turtle in percentage of the max fuel holding capability, using turtle.getFuelLimit().
Code 
print("Fuel level is: ", ( turtle.getFuelLevel() / turtle.getFuelLimit() ) * 100, "%")
Output 
Fuel level is: 9.802 %


FunctionFunctionturtle.getFuelLimit
Returns a number representing the maximum amount of fuel (block moves) the turtle can possibly hold.
Syntax turtle.getFuelLimit()
Returns number fuel
Part of CC:Tweaked
API turtle
ExampleExampleGet fuel limit
Get the maximum amount of fuel the current turtle can have
Code 
print("I can hold ", turtle.getFuelLimit(), "fuel!")
Output 
I can hold 100000 fuel!


FunctionFunctionturtle.getItemCount
Get the number of items in a slot. It will use the current selected slot, if slot is not specified.
Syntax turtle.getItemCount()
Returns number count
Part of CC:Tweaked (source)
API turtle
ExampleExampleGet the item count
Get the item count of the currently selected slot and print it.
Code 
print(turtle.getItemCount())
Output 
5

Turtle.getItemDetail Turtle.getItemSpace

FunctionFunctionturtle.getSelectedSlot
Returns the currently selected item slot.
Syntax turtle.getSelectedSlot()
Returns number slot
Part of CC:Tweaked (source)
API turtle
ExampleExampleGet the selected slot
Get the selected slot and print it.
Code 
print(turtle.getSelectedSlot())
Output 
1

Turtle.inspect Turtle.inspectDown Turtle.inspectUp Turtle.place Turtle.placeDown Turtle.placeUp

FunctionFunctionturtle.refuel
This function attempts to refuel the turtle by consuming amount items from the currently selected slot. If no argument is supplied, it defaults to consuming the whole stack in the slot selected.
Syntax turtle.refuel()
Returns boolean
API turtle
See also turtle.getFuelLevel
ExampleExampleChecking if an Item is Fuel
This function simply checks if an item in the turtle's inventory at the currently selected position can be used as fuel. Since turtle.refuel takes a single argument (which is a number), you can put 0 as it's parameter to check if an item can be used as fuel.
Code 
function checkIfFuel()
  return turtle.refuel(0)
end
ExampleExampleAutomatic Refueling
Checks when your turtle is low on fuel, then refuels it automatically. This function can be run in parallel with other functions. Note that this function uses the above example's function as a function.
Code 
function refuel()
  local fuelLimit = turtle.getFuelLimit()
  while true do
    if turtle.getFuelLevel() < fuelLimit / 4 then
      -- if the fuel level is less than a quarter of a tank...
      -- find an item that we can use as fuel
      for i = 1, 16 do
        -- for every slot in the inventory, do...
        turtle.select(i)
        if checkIfFuel() then
          -- if inventory[i] is a fuel, then...
          turtle.refuel()
          -- refuel by consuming the whole stack
        end
      end
    end
    os.sleep(someDelayTime)
  end
end


FunctionFunctionturtle.select
Sets the currently selected slot to slot
Syntax turtle.select()
API turtle
ExampleExampleMove an Item
This code simply will move an item from slot 4 to slot 7, using turtle.transferTo.
Code 
turtle.select(4)
turtle.transferTo(7)

Turtle.suck Turtle.suckDown Turtle.suckUp

FunctionFunctionturtle.transferTo
Moves an item to another slot. If quantity is empty, it will move the full stack.
Syntax turtle.transferTo()
Returns boolean success
Part of CC:Tweaked (source)
API turtle
ExampleExampleMove an Item
This code will simply move an item from slot 4 to slot 7.
Code 
turtle.select(4)
turtle.transferTo(7)


FunctionFunctionturtle.turnLeft
When called, tries to rotate the turtle 90 degrees to the left. Note that performing this action does not require fuel, and the turtle can not be obstructed or denied from rotating, unless specifically disabled in the config.
Syntax turtle.turnLeft()
Returns boolean success
Part of CC:Tweaked (source)
API turtle
ExampleExampleRotating a turtle
Rotates a turtle 360 degrees counter-clockwise, which equals to 4 steps of 90 degrees to the left, to end facing in the same direction as it started.
Code 
for step = 1, 4 do
  turtle.turnLeft()
end


FunctionFunctionturtle.turnRight
When called, tries to rotate the turtle 90 degrees to the right. Note that performing this action does not require fuel, and the turtle can not be obstructed or denied from rotating, unless specifically disabled in the config.
Syntax turtle.turnRight()
Returns boolean success
Part of CC:Tweaked (source)
API turtle
ExampleExampleRotating a turtle
Rotates a turtle 360 degrees clockwise, which equals to 4 steps of 90 degrees to the right, to end facing in the same direction as it started.
Code 
for step = 1, 4 do
  turtle.turnRight()
end


FunctionFunctionturtle.up
When called, tries to move the turtle up 1 block. The function will return false if the destination is obstructed or protected, or if the turtle is out of fuel. Note Note: This function call consumes fuel, if it is enabled in the mod configuration. It will not work if the turtle has no fuel.
Syntax turtle.up()
Returns boolean success [, string error ]
Part of CC:Tweaked (source)
API turtle
ExampleExampleMoving a turtle
Tries to move the turtle 3 blocks up, and tells the player if this succeeded.
Code 
-- first we set these variables
local blocksSucceeded = 0
local blocksToMove = 3

-- then we initiate a 'for loop'. The for loop will execute the code in it's body multiple times, from 1 to 'blocksToMove' in this case, which we set to 3.
for attempt = 1, blocksToMove do
  local success, error = turtle.up()
  if not success then -- what to do if the move failed
    break -- break will stop the 'for loop' from continuing
  else -- what to do if the move succeeded
    blocksSucceeded = blocksSucceeded + 1
  end
end

-- now we're going to print the results to screen.
if blocksToMove == blocksSucceeded then
  print("Sucessfully moved up by", blocksToMove, "blocks!")
else
  print("Did not move the target of", blocksToMove, ", but moved", blocksSucceeded, "blocks instead!")
end
Retrieved from "https://wiki.computercraft.cc/index.php?title=Turtle_API&oldid=5551"