24,497 ARTICLES
ON THIS WIKI

Turtle (API)

The Turtle API is used in Lua programs to command and interact with a Turtle to accomplish any task desired. The code is case sensitive, always starts with turtle. and the parenthesis () are mandatory.

Movement[edit]

Code Description Return type
turtle.forward() Let the Turtle move forward Boolean success
turtle.back() Let the Turtle move back Boolean success
turtle.up() Let the Turtle move up Boolean success
turtle.down() Let the Turtle move down Boolean success
turtle.turnLeft() The Turtle turns left Boolean true
turtle.turnRight() The Turtle turns right Boolean true

Inventory[edit]

Code Description Return type
turtle.select(slotNumber) The Turtle selects the given slot (1 is top left, 16 is bottom right. Boolean slot <= 16
turtle.getSelectedSlot() Returns the number of the currently selected slot. Number slot number
turtle.getItemCount(slotNumber) Returns the amount of items in the given slot. Number result
turtle.getItemSpace(slotNumber) Returns the amount of space left for items in the given slot. Number result
turtle.getItemDetail(slotNumber) Returns the ID string, count and damage values of currently selected slot or slotNum. Number table data
turtle.compare() Returns true if the block in front is the same as the one in the selected slot. Boolean result
turtle.compareUp() Compares above. Boolean result
turtle.compareDown() Compares below. Boolean result
turtle.compareTo(slotNumber) Returns true if the item in the current selected slot and the given slot are the same. Boolean result
turtle.refuel() Consumes the fuel items in the current selected slot. Yields false if there is no fuel. Boolean success
turtle.getFuelLevel() Returns the current fuel level of the turtle, this is the number of blocks the turtle can move. In no fuel needed mode, it returns unlimited. Number fuel
turtle.craft(quantity) Crafts the specified amount of items using ingredients in the inventory. Boolean success
turtle.equip.right() Attempts to equip an item in the current slot to the turtle's right side, switching if already equipped. Boolean success
turtle.equip.left() Attempts to equip an item in the current slot to the turtle's left side, switching if already equipped. Boolean success
turtle.transferTo(slotNumber, amount) Transfers amount of items from the selected slot to slotNumber. If amount isn't specified, will attempt to transfer everything in the selected slot. Boolean success

Interaction[edit]

Code Description Return type
turtle.place(text) Places a block of the selected slot in front. Engraves text when placing a signs. Boolean success
turtle.placeUp() Places a block of the selected slot above. Boolean success
turtle.placeDown() Places a block of the selected slot below. Boolean success
turtle.detect() Detects if there is a block in front. Boolean result
turtle.detectUp() Detects if there is a block above. Boolean result
turtle.detectDown() Detects if there is a block below. Boolean result
turtle.drop(amount) Drops amount of items from the last selected slot, drops all if amount not specified [1]. Boolean success
turtle.dropUp(amount) Drops amount of items from the last selected slot above, drops all if amount not specified [1] Boolean success
turtle.dropDown(amount) Drops amount of items from the last selected slot below, drops all if amount not specified [1] Boolean success
turtle.suck() Picks up an item stack of any number, from the ground or an inventory in front of the turtle. If the turtle can't pick up the item, the function yields false. Boolean success
turtle.suckUp() Picks up an item stack of any number, from the ground or an inventory above the turtle. If the turtle can't pick up the item, the function yields false. Boolean success
turtle.suckDown() Picks up an item stack of any number, from the ground or an inventory below the turtle. If the turtle can't pick up the item, the function yields false. Boolean success
turtle.attack() Attacks in front of the turtle. Boolean success
turtle.attackUp() Attacks the space above the turtle. Boolean success
turtle.attackDown() Attacks the space below the turtle. Boolean success
turtle.dig() [2] Breaks the block in front. Boolean success
turtle.digUp() Breaks the block Above it. Boolean success
turtle.digDown() Breaks the block Below it. Boolean success
turtle.inspect() Returns the ID string and metadata of the block in front. Boolean success; table data/ string; error message
turtle.inspectUp() Inspects the block above. Boolean success; table data/ string; error message
turtle.inspectDown() Inspects the block below. Boolean success; table data/ string; error message

Note[edit]

  1. 1.0 1.1 1.2 It will place into an inventory in front if available, returning false if the inventory is full.
  2. A Farming Turtle will till dirt with the dig command instead of breaking blocks. A Melee Turtle doesn't respond.

Trivia[edit]

  • Trivia: During the 1.4 beta, turtle.getFuelLevel() in softcore (turtleneedsfuel = false config setting) returned 9000.