turtle

The turtle API allows you to control your turtle.

forward()Move the turtle forward one block.
back()Move the turtle backwards one block.
up()Move the turtle up one block.
down()Move the turtle down one block.
turnLeft()Rotate the turtle 90 degress to the left.
turnRight()Rotate the turtle 90 degress to the right.
dig([side])Attempt to break the block in front of the turtle.
digUp([side])Attempt to break the block above the turtle.
digDown([side])Attempt to break the block below the turtle.
place([text])Place a block or item into the world in front of the turtle.
placeUp([text])Place a block or item into the world above the turtle.
placeDown([text])Place a block or item into the world below the turtle.
drop([count])Drop the currently selected stack into the inventory in front of the turtle, or as an item into the world if there is no inventory.
dropUp([count])Drop the currently selected stack into the inventory above the turtle, or as an item into the world if there is no inventory.
dropDown([count])Drop the currently selected stack into the inventory in front of the turtle, or as an item into the world if there is no inventory.
select(slot)Change the currently selected slot.
getItemCount([slot])Get the number of items in the given slot.
getItemSpace([slot])Get the remaining number of items which may be stored in this stack.
detect()Check if there is a solid block in front of the turtle.
detectUp()Check if there is a solid block above the turtle.
detectDown()Check if there is a solid block below the turtle.
compare()Check if the block in front of the turtle is equal to the item in the currently selected slot.
compareUp()Check if the block above the turtle is equal to the item in the currently selected slot.
compareDown()Check if the block below the turtle is equal to the item in the currently selected slot.
attack([side])Attack the entity in front of the turtle.
attackUp([side])Attack the entity above the turtle.
attackDown([side])Attack the entity below the turtle.
suck([count])Suck an item from the inventory in front of the turtle, or from an item floating in the world.
suckUp([count])Suck an item from the inventory above the turtle, or from an item floating in the world.
suckDown([count])Suck an item from the inventory below the turtle, or from an item floating in the world.
getFuelLevel()Get the maximum amount of fuel this turtle currently holds.
refuel([count])Refuel this turtle.
compareTo(slot)Compare the item in the currently selected slot to the item in another slot.
transferTo(slot [, count])Move an item from the selected slot to another one.
getSelectedSlot()Get the currently selected slot.
getFuelLimit()Get the maximum amount of fuel this turtle can hold.
equipLeft()Equip (or unequip) an item on the left side of this turtle.
equipRight()Equip (or unequip) an item on the right side of this turtle.
inspect()Get information about the block in front of the turtle.
inspectUp()Get information about the block above the turtle.
inspectDown()Get information about the block below the turtle.
getItemDetail([slot [, detailed]])Get detailed information about the items in the given slot.
craft([limit=64])Craft a recipe based on the turtle's inventory.
nativeThe builtin turtle API, without any generated helper functions.
forward()Source

Move the turtle forward one block.

Returns

  1. boolean Whether the turtle could successfully move.
  2. string | nil The reason the turtle could not move.
back()Source

Move the turtle backwards one block.

Returns

  1. boolean Whether the turtle could successfully move.
  2. string | nil The reason the turtle could not move.
up()Source

Move the turtle up one block.

Returns

  1. boolean Whether the turtle could successfully move.
  2. string | nil The reason the turtle could not move.
down()Source

Move the turtle down one block.

Returns

  1. boolean Whether the turtle could successfully move.
  2. string | nil The reason the turtle could not move.
turnLeft()Source

Rotate the turtle 90 degress to the left.

Returns

  1. boolean Whether the turtle could successfully turn.
  2. string | nil The reason the turtle could not turn.
turnRight()Source

Rotate the turtle 90 degress to the right.

Returns

  1. boolean Whether the turtle could successfully turn.
  2. string | nil The reason the turtle could not turn.
dig([side])Source

Attempt to break the block in front of the turtle.

This requires a turtle tool capable of breaking the block. Diamond pickaxes (mining turtles) can break any vanilla block, but other tools (such as axes) are more limited.

Parameters

  1. side? string The specific tool to use. Should be "left" or "right".

Returns

  1. boolean Whether a block was broken.
  2. string | nil The reason no block was broken.
digUp([side])Source

Attempt to break the block above the turtle. See dig for full details.

Parameters

  1. side? string The specific tool to use.

Returns

  1. boolean Whether a block was broken.
  2. string | nil The reason no block was broken.
digDown([side])Source

Attempt to break the block below the turtle. See dig for full details.

Parameters

  1. side? string The specific tool to use.

Returns

  1. boolean Whether a block was broken.
  2. string | nil The reason no block was broken.
place([text])Source

Place a block or item into the world in front of the turtle.

"Placing" an item allows it to interact with blocks and entities in front of the turtle. For instance, buckets can pick up and place down fluids, and wheat can be used to breed cows. However, you cannot use place to perform arbitrary block interactions, such as clicking buttons or flipping levers.

Parameters

  1. text? string When placing a sign, set its contents to this text.

Returns

  1. boolean Whether the block could be placed.
  2. string | nil The reason the block was not placed.
placeUp([text])Source

Place a block or item into the world above the turtle.

Parameters

  1. text? string When placing a sign, set its contents to this text.

Returns

  1. boolean Whether the block could be placed.
  2. string | nil The reason the block was not placed.

See also

  • place For more information about placing items.
placeDown([text])Source

Place a block or item into the world below the turtle.

Parameters

  1. text? string When placing a sign, set its contents to this text.

Returns

  1. boolean Whether the block could be placed.
  2. string | nil The reason the block was not placed.

See also

  • place For more information about placing items.
drop([count])Source

Drop the currently selected stack into the inventory in front of the turtle, or as an item into the world if there is no inventory.

Parameters

  1. count? number The number of items to drop. If not given, the entire stack will be dropped.

Returns

  1. boolean Whether items were dropped.
  2. string | nil The reason the no items were dropped.

Throws

  • If dropping an invalid number of items.

See also

dropUp([count])Source

Drop the currently selected stack into the inventory above the turtle, or as an item into the world if there is no inventory.

Parameters

  1. count? number The number of items to drop. If not given, the entire stack will be dropped.

Returns

  1. boolean Whether items were dropped.
  2. string | nil The reason the no items were dropped.

Throws

  • If dropping an invalid number of items.

See also

dropDown([count])Source

Drop the currently selected stack into the inventory in front of the turtle, or as an item into the world if there is no inventory.

Parameters

  1. count? number The number of items to drop. If not given, the entire stack will be dropped.

Returns

  1. boolean Whether items were dropped.
  2. string | nil The reason the no items were dropped.

Throws

  • If dropping an invalid number of items.

See also

select(slot)Source

Change the currently selected slot.

The selected slot is determines what slot actions like drop or getItemCount act on.

Parameters

  1. slot number The slot to select.

Returns

  1. true When the slot has been selected.

Throws

  • If the slot is out of range.

See also

getItemCount([slot])Source

Get the number of items in the given slot.

Parameters

  1. slot? number The slot we wish to check. Defaults to the selected slot.

Returns

  1. number The number of items in this slot.

Throws

  • If the slot is out of range.

getItemSpace([slot])Source

Get the remaining number of items which may be stored in this stack.

For instance, if a slot contains 13 blocks of dirt, it has room for another 51.

Parameters

  1. slot? number The slot we wish to check. Defaults to the selected slot.

Returns

  1. number The space left in in this slot.

Throws

  • If the slot is out of range.

detect()Source

Check if there is a solid block in front of the turtle. In this case, solid refers to any non-air or liquid block.

Returns

  1. boolean If there is a solid block in front.
detectUp()Source

Check if there is a solid block above the turtle. In this case, solid refers to any non-air or liquid block.

Returns

  1. boolean If there is a solid block in front.
detectDown()Source

Check if there is a solid block below the turtle. In this case, solid refers to any non-air or liquid block.

Returns

  1. boolean If there is a solid block in front.
compare()Source

Check if the block in front of the turtle is equal to the item in the currently selected slot.

Returns

  1. boolean If the block and item are equal.
compareUp()Source

Check if the block above the turtle is equal to the item in the currently selected slot.

Returns

  1. boolean If the block and item are equal.
compareDown()Source

Check if the block below the turtle is equal to the item in the currently selected slot.

Returns

  1. boolean If the block and item are equal.
attack([side])Source

Attack the entity in front of the turtle.

Parameters

  1. side? string The specific tool to use.

Returns

  1. boolean Whether an entity was attacked.
  2. string | nil The reason nothing was attacked.
attackUp([side])Source

Attack the entity above the turtle.

Parameters

  1. side? string The specific tool to use.

Returns

  1. boolean Whether an entity was attacked.
  2. string | nil The reason nothing was attacked.
attackDown([side])Source

Attack the entity below the turtle.

Parameters

  1. side? string The specific tool to use.

Returns

  1. boolean Whether an entity was attacked.
  2. string | nil The reason nothing was attacked.
suck([count])Source

Suck an item from the inventory in front of the turtle, or from an item floating in the world.

This will pull items into the first acceptable slot, starting at the currently selected one.

Parameters

  1. count? number The number of items to suck. If not given, up to a stack of items will be picked up.

Returns

  1. boolean Whether items were picked up.
  2. string | nil The reason the no items were picked up.

Throws

  • If given an invalid number of items.

suckUp([count])Source

Suck an item from the inventory above the turtle, or from an item floating in the world.

Parameters

  1. count? number The number of items to suck. If not given, up to a stack of items will be picked up.

Returns

  1. boolean Whether items were picked up.
  2. string | nil The reason the no items were picked up.

Throws

  • If given an invalid number of items.

suckDown([count])Source

Suck an item from the inventory below the turtle, or from an item floating in the world.

Parameters

  1. count? number The number of items to suck. If not given, up to a stack of items will be picked up.

Returns

  1. boolean Whether items were picked up.
  2. string | nil The reason the no items were picked up.

Throws

  • If given an invalid number of items.

getFuelLevel()Source

Get the maximum amount of fuel this turtle currently holds.

Returns

  1. number The current amount of fuel a turtle this turtle has.

Or

  1. "unlimited" If turtles do not consume fuel when moving.

See also

refuel([count])Source

Refuel this turtle.

While most actions a turtle can perform (such as digging or placing blocks), moving consumes fuel from the turtle's internal buffer. If a turtle has no fuel, it will not move.

refuel refuels the turtle, consuming fuel items (such as coal or lava buckets) from the currently selected slot and converting them into energy. This finishes once the turtle is fully refuelled or all items have been consumed.

Parameters

  1. count? number The maximum number of items to consume. One can pass 0 to check if an item is combustable or not.

Returns

  1. true If the turtle was refuelled.

Or

  1. false If the turtle was not refuelled.
  2. string The reason the turtle was not refuelled (

Throws

  • If the refuel count is out of range.

Usage

  • Refuel a turtle from the currently selected slot.

    local level = turtle.getFuelLevel()
    if new_level == "unlimited" then error("Turtle does not need fuel", 0) end
    
    local ok, err = turtle.refuel()
    if ok then
      local new_level = turtle.getFuelLevel()
      print(("Refuelled %d, current level is %d"):format(new_level - level, new_level))
    else
      printError(err)
    end
  • Check if the current item is a valid fuel source.

    local is_fuel, reason = turtle.refuel(0)
    if not is_fuel then printError(reason) end

See also

compareTo(slot)Source

Compare the item in the currently selected slot to the item in another slot.

Parameters

  1. slot number The slot to compare to.

Returns

  1. boolean If the two items are equal.

Throws

  • If the slot is out of range.

transferTo(slot [, count])Source

Move an item from the selected slot to another one.

Parameters

  1. slot number The slot to move this item to.
  2. count? number The maximum number of items to move.

Returns

  1. boolean If some items were successfully moved.

Throws

  • If the slot is out of range.

  • If the number of items is out of range.

getSelectedSlot()Source

Get the currently selected slot.

Returns

  1. number The current slot.

See also

getFuelLimit()Source

Get the maximum amount of fuel this turtle can hold.

By default, normal turtles have a limit of 20,000 and advanced turtles of 100,000.

Returns

  1. number The maximum amount of fuel a turtle can hold.

Or

  1. "unlimited" If turtles do not consume fuel when moving.

See also

equipLeft()Source

Equip (or unequip) an item on the left side of this turtle.

This finds the item in the currently selected slot and attempts to equip it to the left side of the turtle. The previous upgrade is removed and placed into the turtle's inventory. If there is no item in the slot, the previous upgrade is removed, but no new one is equipped.

Returns

  1. true If the item was equipped.

Or

  1. false If we could not equip the item.
  2. string The reason equipping this item failed.

See also

equipRight()Source

Equip (or unequip) an item on the right side of this turtle.

This finds the item in the currently selected slot and attempts to equip it to the right side of the turtle. The previous upgrade is removed and placed into the turtle's inventory. If there is no item in the slot, the previous upgrade is removed, but no new one is equipped.

Returns

  1. true If the item was equipped.

Or

  1. false If we could not equip the item.
  2. string The reason equipping this item failed.

See also

inspect()Source

Get information about the block in front of the turtle.

Returns

  1. boolean Whether there is a block in front of the turtle.
  2. table | string Information about the block in front, or a message explaining that there is no block.

Usage

  • local has_block, data = turtle.inspect()
    if has_block then
      print(textutils.serialize(data))
      -- {
      --   name = "minecraft:oak_log",
      --   state = { axis = "x" },
      --   tags = { ["minecraft:logs"] = true, ... },
      -- }
    else
      print("No block in front of the turtle")
    end
inspectUp()Source

Get information about the block above the turtle.

Returns

  1. boolean Whether there is a block above the turtle.
  2. table | string Information about the above below, or a message explaining that there is no block.
inspectDown()Source

Get information about the block below the turtle.

Returns

  1. boolean Whether there is a block below the turtle.
  2. table | string Information about the block below, or a message explaining that there is no block.
getItemDetail([slot [, detailed]])Source

Get detailed information about the items in the given slot.

Parameters

  1. slot? number The slot to get information about. Defaults to the selected slot.
  2. detailed? boolean

    Whether to include "detailed" information. When true the method will contain much

                 more information about the item at the cost of taking longer to run.

Returns

  1. nil | table Information about the given slot, or nil if it is empty.

Throws

  • If the slot is out of range.

Usage

See also

craft([limit=64])Source

Craft a recipe based on the turtle's inventory.

The turtle's inventory should set up like a crafting grid. For instance, to craft sticks, slots 1 and 5 should contain planks. All other slots should be empty, including those outside the crafting "grid".

Parameters

  1. limit? number = 64 The maximum number of crafting steps to run.

Returns

  1. true If crafting succeeds.

Or

  1. false If crafting fails.
  2. string A string describing why crafting failed.

Throws

  • When limit is less than 1 or greater than 64.

nativeSource
Deprecated

The builtin turtle API, without any generated helper functions.

Generally you should not need to use this table - it only exists for backwards compatibility reasons.