Turtle API

The turtle API is exclusive to turtles and advanced turtles.

Functionturtle.attack
Attacks the entity in direction and range
Syntax turtle.attack(
  • toolSide? : string
)
Returns bool didAttack
Part of CC:Tweaked (source)
API turtle
ExampleCheck for hit
See if it was able to hit the entity it targeted
Code 
<nowiki>
local didHit = turtle.attack()
print(didHit)
    </nowiki>
Output 
false
1
Functionturtle.attackDown
Attacks the entity under the turtle
Syntax turtle.attackDown(
  • toolSide? : string
)
Returns bool didAttack
Part of CC:Tweaked (source)
API turtle
ExampleCheck for hit
See if it was able to hit the entity it targeted
Code 
<nowiki>
local didHit = turtle.attack()
print(didHit)
    </nowiki>
Output 
false
Functionturtle.attackUp
Attacks the entity over the turtle
Syntax turtle.attackUp(
  • toolSide? : string
)
Returns bool didAttack
Part of CC:Tweaked (source)
API turtle
ExampleCheck for hit
See if it was able to hit the entity it targeted
Code 
<nowiki>
local didHit = turtle.attack()
print(didHit)
    </nowiki>
Output 
false
Functionturtle.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: 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
ExampleMoving a turtle
Tries to move the turtle 3 blocks backward, and tells the player if this succeeded.
Code 
<nowiki>
-- 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
    </nowiki>

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

Functionturtle.craft
Requires the turtle to have a crafting table equipped.

Crafts items if the turtle's inventory contains a valid recipe and nothing else. It is not limited to the top-left nine slots - as long as its inventory contains the necessary pattern of items and is free of any other items (including ones outside of the space the crafting pattern occupies), it can craft. Produced items will fill the selected slot preferentially and the ones after it if it is full. It is not limited to crafting a single stack at once - for example, if you put a stack of redstone blocks in a turtle and execute this, nine stacks of redstone will be produced.

The argument "limit" limits the amount of times the crafting recipe will be made. If enough items to make it multiple times are provided, but a limit lower than this is specified, it will make the recipe the specified amount of times and leave the remaining items in their places. If "limit" is 0, it will return true if an item could be crafted.

The first return value represents whether crafting was successful or not. If an error occurs it will be false and the second return value will contain the error message. For example, if the turtle does not contain a valid recipe when this is executed, it will return false and "No matching recipes". If crafting is successful it will return only true.
Syntax turtle.craft(
  • limit? : number
)
Returns boolean true | boolean false, string
Part of CC:Tweaked (source)
API turtle
Functionturtle.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
ExampleDetecting 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!
Functionturtle.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
ExampleDetecting 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!
Functionturtle.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
ExampleDetecting 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!
Functionturtle.dig
Breaks the block in front of the turtle.
Syntax turtle.dig(
  • toolSide? : string
)
Returns bool didDig
Part of CC:Tweaked (source)
API turtle
ExampleCheck for dig
See if it was able to dig.
Code 
<nowiki>
local didDig = turtle.dig()
print(didDig)
    </nowiki>
Output 
false
1
Functionturtle.digDown
Breaks the block in beneath the turtle.
Syntax turtle.digDown(
  • toolSide? : string
)
Returns bool didDig
Part of CC:Tweaked (source)
API turtle
ExampleCheck for dig
See if it was able to dig.
Code 
<nowiki>
local didDig = turtle.digDown()
print(didDig)
    </nowiki>
Output 
false
1
Functionturtle.digUp
Breaks the block above the turtle.
Syntax turtle.digUp(
  • toolSide? : string
)
Returns bool didDig
Part of CC:Tweaked (source)
API turtle
ExampleCheck for dig
See if it was able to dig.
Code 
<nowiki>
local didDig = turtle.digUp()
print(didDig)
    </nowiki>
Output 
false
1
Functionturtle.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: 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
ExampleMoving a turtle
Tries to move the turtle 3 blocks down, and tells the player if this succeeded.
Code 
<nowiki>
-- 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
    </nowiki>
Functionturtle.drop
Drops the item item in the turtle’s selected slot in front of the turtle.
Syntax turtle.drop()
Returns boolean success
Part of Lua (source)
API turtle
ExampleDrop a ítem in front of the turtle.
Prints if turtle successfully dropped the item.
Code 
print(turtle.drop())
Output true
Functionturtle.dropDown
Drops the item item in the turtle’s selected slot below the turtle.
Syntax turtle.dropDown()
Returns boolean success
Part of Lua (source)
API turtle
ExampleDrop a ítem below the turtle.
Prints if turtle successfully dropped the item.
Code 
print(turtle.dropDown())
Output true
Functionturtle.dropUp
Drops the item item in the turtle’s selected slot above the turtle.
Syntax turtle.dropUp()
Returns boolean success
Part of Lua (source)
API turtle
ExampleDrop a ítem above the turtle.
Prints if turtle successfully dropped the item.
Code 
print(turtle.dropUp())
Output true
Functionturtle.equipLeft
When called, will equip the item currently selected onto the left side of the turtle. If no item is selected, it will dequip the item on the left side.
Syntax turtle.equipLeft()
Returns boolean success
Part of CC:Tweaked (source)
API turtle
ExampleEquip a diamond pickaxe
Equips a diamond pickaxe on the turtle, turning it into a mining turtle. This presumes that the pickaxe is in slot 1 of the turtle.
Code 
<nowiki>
turtle.equipLeft();
    </nowiki>
Functionturtle.equipRight
When called, will equip the item currently selected onto the right side of the turtle. If no item is selected, it will dequip the item on the right side.
Syntax turtle.equipRight()
Returns boolean success
Part of CC:Tweaked (source)
API turtle
ExampleEquip a diamond pickaxe
Equips a diamond pickaxe on the turtle, turning it into a mining turtle. This presumes that the pickaxe is in slot 1 of the turtle.
Code 
<nowiki>
turtle.equipRight();
    </nowiki>
Functionturtle.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: 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
ExampleMoving a turtle
Tries to move the turtle 3 blocks forward, and tells the player if this succeeded.
Code 
<nowiki>
-- 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
    </nowiki>
Functionturtle.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
ExampleGet 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!
ExampleGet 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 %
Functionturtle.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
ExampleGet 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!
Functionturtle.getItemCount
Get the number of items in a slot. It will use the current selected slot, if slot is not specified.
Syntax turtle.getItemCount(
  • slot? : number
)
Returns number count
Part of CC:Tweaked (source)
API turtle
ExampleGet the item count
Get the item count of the currently selected slot and print it.
Code 
<nowiki>
print(turtle.getItemCount())
  </nowiki>
Output 
5

Turtle.getItemDetail Turtle.getItemSpace

Functionturtle.getSelectedSlot
Returns the currently selected item slot.
Syntax turtle.getSelectedSlot()
Returns number slot
Part of CC:Tweaked (source)
API turtle
ExampleGet the selected slot
Get the selected slot and print it.
Code 
<nowiki>
print(turtle.getSelectedSlot())
    </nowiki>
Output 
1

Turtle.inspect Turtle.inspectDown Turtle.inspectUp

Functionturtle.place
Places a block in the turtle’s selected slot in front of the turtle.
Syntax turtle.place()
Returns boolean success
Part of Lua (source)
API peripheral
ExamplePlace a block
Prints if turtle successfully placed the block.
Code 
print(turtle.place())
Output true
Functionturtle.placeDown
Places a block in the turtle’s selected slot below the turtle.
Syntax turtle.placeDown()
Returns boolean success
Part of Lua (source)
API turtle
ExamplePlace a block below the turtle
Prints if turtle successfully placed the block.
Code 
print(turtle.placeDown())
Output true
Functionturtle.placeUp
Places the block in the turtle’s selected slot above the turtle.
Syntax turtle.placeUp()
Returns boolean success
Part of Lua (source)
API turtle
ExamplePlace a block above the turtle
Prints if turtle successfully placed the block.
Code 
print(turtle.placeUp())
Output true
Functionturtle.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(
  • amount? : number
)
Returns boolean
API turtle
See also turtle.getFuelLevel
ExampleChecking 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
ExampleAutomatic 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
Functionturtle.select
Sets the currently selected slot to slot
Syntax turtle.select(
  • slot : number
)
API turtle
ExampleMove 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)
Functionturtle.place
Picks up a item in front of the turtle
Syntax turtle.place()
Returns integer amount
Part of Lua (source)
API turtle
ExamplePickup a item
Prints the amount of items the turtle picks up.
Code 
print(turtle.suck())
Output true
Functionturtle.suckDown
Picks up a item below the turtle
Syntax turtle.suckDown()
Returns integer amount
Part of Lua (source)
API turtle
ExamplePickup a item below the turtle.
Prints the amount of items the turtle picks up.
Code 
print(turtle.suckDown())
Output true
Functionturtle.place
Picks up a item above the turtle
Syntax turtle.place()
Returns integer amount
Part of Lua (source)
API turtle
ExamplePickup a item above the turtle.
Prints the amount of items the turtle picks up.
Code 
print(turtle.suckUp())
Output 3
Functionturtle.transferTo
Moves an item to another slot. If quantity is empty, it will move the full stack.
Syntax turtle.transferTo(
  • slot : number
  • quantity? : number
)
Returns boolean success
Part of CC:Tweaked (source)
API turtle
ExampleMove an Item
This code will simply move an item from slot 4 to slot 7.
Code 
turtle.select(4)
turtle.transferTo(7)
Functionturtle.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
ExampleRotating 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 
<nowiki>
for step = 1, 4 do
  turtle.turnLeft()
end
    </nowiki>
Functionturtle.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
ExampleRotating 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 
<nowiki>
for step = 1, 4 do
  turtle.turnRight()
end
    </nowiki>
Functionturtle.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: 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
ExampleMoving a turtle
Tries to move the turtle 3 blocks up, and tells the player if this succeeded.
Code 
<nowiki>
-- 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
    </nowiki>
This article is issued from Computercraft. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.