Difference between revisions of "Turtle (API)"

From ComputerCraft Wiki
Jump to: navigation, search
(Minecraft 1.5 changed how furnaces work, so this is inaccurate)
(Add tool side arguments to dig and attack methods)
 
(14 intermediate revisions by 6 users not shown)
Line 24: Line 24:
 
|-{{row-lightgreen}}
 
|-{{row-lightgreen}}
 
|{{type|boolean}} success
 
|{{type|boolean}} success
|[[turtle.craft]]({{type|int}} quantity)
+
|[[turtle.craft]]({{type|number}} quantity)
 
|Craft items using ingredients anywhere in the turtle's inventory and place results in the active slot. If a quantity is specified, it will craft only up to that many items, otherwise, it will craft as many of the items as possible.
 
|Craft items using ingredients anywhere in the turtle's inventory and place results in the active slot. If a quantity is specified, it will craft only up to that many items, otherwise, it will craft as many of the items as possible.
|
+
|1.4
 
|-
 
|-
 
|{{type|boolean}} success
 
|{{type|boolean}} success
 
|[[turtle.forward]]()
 
|[[turtle.forward]]()
 
|Try to move the turtle forward
 
|Try to move the turtle forward
|
+
|?
 
|-  
 
|-  
 
|{{type|boolean}} success
 
|{{type|boolean}} success
 
|[[turtle.back]]()
 
|[[turtle.back]]()
 
|Try to move the turtle backward
 
|Try to move the turtle backward
|
+
|?
 
|-
 
|-
 
|{{type|boolean}} success
 
|{{type|boolean}} success
 
|[[turtle.up]]()
 
|[[turtle.up]]()
 
|Try to move the turtle up
 
|Try to move the turtle up
|
+
|?
 
|-
 
|-
 
|{{type|boolean}} success
 
|{{type|boolean}} success
 
|[[turtle.down]]()
 
|[[turtle.down]]()
 
|Try to move the turtle down  
 
|Try to move the turtle down  
|
+
|?
 
|-
 
|-
 
|{{type|boolean}} success
 
|{{type|boolean}} success
 
|[[turtle.turnLeft]]()
 
|[[turtle.turnLeft]]()
 
|Turn the turtle left
 
|Turn the turtle left
|
+
|?
 
|-
 
|-
 
|{{type|boolean}} success
 
|{{type|boolean}} success
 
|[[turtle.turnRight]]()
 
|[[turtle.turnRight]]()
 
|Turn the turtle right
 
|Turn the turtle right
|
+
|?
 
|-
 
|-
 
|{{type|boolean}} success
 
|{{type|boolean}} success
|[[turtle.select]]({{type|int}} slotNum)
+
|[[turtle.select]]({{type|number}} slotNum)
|Make the turtle select slot ''slotNum'' (1 is top left, 16 (9 in 1.33 and earlier) is bottom right)
+
|Make the turtle select slot <var>slotNum</var> (1 is top left, 16 (9 in 1.33 and earlier) is bottom right)
|
+
|?
 
|-
 
|-
|{{type|int}} count
+
|{{type|number}} slot
|[[turtle.getItemCount]]({{type|int}} slotNum)
+
|[[turtle.getSelectedSlot]]()
|Counts how many items are in slot ''slotNum''
+
|Indicates the currently selected inventory slot
|
+
| 1.6
 
|-
 
|-
|{{type|int}} count
+
|{{type|number}} count
|[[turtle.getItemSpace]]({{type|int}} slotNum)
+
|[[turtle.getItemCount]]([<nowiki/>{{type|number}} slotNum])
|Counts how many remaining items you need to fill the stack in slot ''slotNum''
+
|Counts how many items are in the currently selected slot or, if specified, <var>slotNum</var> slot
|
+
|?
 +
|-
 +
|{{type|number}} count
 +
|[[turtle.getItemSpace]]([<nowiki/>{{type|number}} slotNum])
 +
|Counts how many remaining items you need to fill the stack in the currently selected slot or, if specified, <var>slotNum</var> slot
 +
|?
 +
|-
 +
|{{type|table}} data
 +
|[[turtle.getItemDetail]]([<nowiki/>{{type|number}} slotNum])
 +
|Returns the ID string, count and damage values of currently selected slot or, if specified, <var>slotNum</var> slot
 +
|1.64
 +
|-
 +
|{{type|boolean}} success
 +
|[[turtle.equipLeft]]()
 +
|Attempts to equip an item in the current slot to the turtle's left side, switching the previously equipped item back into the inventory
 +
|1.6
 +
|-
 +
|{{type|boolean}} success
 +
|[[turtle.equipRight]]()
 +
|Attempts to equip an item in the current slot to the turtle's right side, switching the previously equipped item back into the inventory
 +
|1.6
 
|-{{row-lightred}}
 
|-{{row-lightred}}
 
|{{type|boolean}} success
 
|{{type|boolean}} success
|[[turtle.attack]]()
+
|[[turtle.attack]]([<nowiki />{{type|string}} toolSide])
 
|Attacks in front of the turtle.
 
|Attacks in front of the turtle.
 
| 1.4
 
| 1.4
 
|-{{row-lightred}}
 
|-{{row-lightred}}
 
|{{type|boolean}} success  
 
|{{type|boolean}} success  
|[[turtle.attackUp]]()
+
|[[turtle.attackUp]]([<nowiki />{{type|string}} toolSide])
 
|Attacks above the turtle.
 
|Attacks above the turtle.
 
| 1.4
 
| 1.4
 
|-{{row-lightred}}
 
|-{{row-lightred}}
 
|{{type|boolean}} success
 
|{{type|boolean}} success
|[[turtle.attackDown]]()
+
|[[turtle.attackDown]]([<nowiki />{{type|string}} toolSide])
 
|Attacks under the turtle.
 
|Attacks under the turtle.
 
| 1.4
 
| 1.4
 
|-{{row-lightyellow}}
 
|-{{row-lightyellow}}
 
|{{type|boolean}} success
 
|{{type|boolean}} success
|[[turtle.dig]]()
+
|[[turtle.dig]]([<nowiki />{{type|string}} toolSide])
 
|Breaks the block in front. With hoe: tills the dirt in front of it.
 
|Breaks the block in front. With hoe: tills the dirt in front of it.
|
+
|?
 
|-{{row-lightyellow}}
 
|-{{row-lightyellow}}
 
|{{type|boolean}} success
 
|{{type|boolean}} success
|[[turtle.digUp]]()
+
|[[turtle.digUp]]([<nowiki />{{type|string}} toolSide])
|Breaks the block above. With hoe: tills the dirt above it.
+
|Breaks the block above.
|
+
|?
 
|-{{row-lightyellow}}
 
|-{{row-lightyellow}}
 
|{{type|boolean}} success
 
|{{type|boolean}} success
|[[turtle.digDown]]()
+
|[[turtle.digDown]]([<nowiki />{{type|string}} toolSide])
|Breaks the block below. With hoe: tills the dirt below it.
+
|Breaks the block below. With hoe: tills the dirt beneath the space below it.
|
+
|?
 
|-
 
|-
 
|{{type|boolean}} success
 
|{{type|boolean}} success
 
|[[turtle.place]]([<nowiki></nowiki>{{type|string}} signText])
 
|[[turtle.place]]([<nowiki></nowiki>{{type|string}} signText])
|Places a block of the selected slot in front. Engrave ''signText'' on signs if provided.
+
|Places a block of the selected slot in front. Engrave <var>signText</var> on signs if provided. Collects [[water]] or [[lava]] if the currently selected slot is an empty bucket.
 
| 1.4
 
| 1.4
 
|-
 
|-
 
|{{type|boolean}} success
 
|{{type|boolean}} success
 
|[[turtle.placeUp]]()
 
|[[turtle.placeUp]]()
|Places a block of the selected slot above
+
|Places a block of the selected slot above. Collects water or lava if the currently selected slot is an empty bucket.
|
+
|?
 
|-
 
|-
 
|{{type|boolean}} success
 
|{{type|boolean}} success
 
|[[turtle.placeDown]]()
 
|[[turtle.placeDown]]()
|Places a block of the selected slot below
+
|Places a block of the selected slot below. Collects water or lava if the currently selected slot is an empty bucket.
|
+
|?
 
|-
 
|-
 
|{{type|boolean}} result
 
|{{type|boolean}} result
 
|[[turtle.detect]]()
 
|[[turtle.detect]]()
 
|Detects if there is a block in front.  Does not detect mobs.
 
|Detects if there is a block in front.  Does not detect mobs.
|
+
|?
 
|-
 
|-
 
|{{type|boolean}} result
 
|{{type|boolean}} result
 
|[[turtle.detectUp]]()
 
|[[turtle.detectUp]]()
 
|Detects if there is a block above
 
|Detects if there is a block above
|
+
|?
 
|-
 
|-
 
|{{type|boolean}} result
 
|{{type|boolean}} result
 
|[[turtle.detectDown]]()
 
|[[turtle.detectDown]]()
 
|Detects if there is a block below
 
|Detects if there is a block below
|
+
|?
 +
|-
 +
|{{type|boolean}} success, {{type|table}} data/{{type|string}} error message
 +
|[[turtle.inspect]]()
 +
|Returns the ID string and metadata of the block in front of the Turtle
 +
|1.64
 +
|-
 +
|{{type|boolean}} success, {{type|table}} data/{{type|string}} error message
 +
|[[turtle.inspectUp]]()
 +
|Returns the ID string and metadata of the block above the Turtle
 +
|1.64
 +
|-
 +
|{{type|boolean}} success, {{type|table}} data/{{type|string}} error message
 +
|[[turtle.inspectDown]]()
 +
|Returns the ID string and metadata of the block below the Turtle
 +
|1.64
 
|-
 
|-
 
|{{type|boolean}} result
 
|{{type|boolean}} result
 
|[[turtle.compare]]()
 
|[[turtle.compare]]()
 
|Detects if the block in front is the same as the one in the currently selected slot
 
|Detects if the block in front is the same as the one in the currently selected slot
|
+
|1.31
 
|-
 
|-
 
|{{type|boolean}} result
 
|{{type|boolean}} result
 
|[[turtle.compareUp]]()
 
|[[turtle.compareUp]]()
 
|Detects if the block above is the same as the one in the currently selected slot
 
|Detects if the block above is the same as the one in the currently selected slot
|
+
|?
 
|-
 
|-
 
|{{type|boolean}} result
 
|{{type|boolean}} result
 
|[[turtle.compareDown]]()
 
|[[turtle.compareDown]]()
 
|Detects if the block below is the same as the one in the currently selected slot
 
|Detects if the block below is the same as the one in the currently selected slot
|
+
|?
 
|-
 
|-
 
|{{type|boolean}} result
 
|{{type|boolean}} result
|[[turtle.compareTo]]({{type|int}} slot)
+
|[[turtle.compareTo]]({{type|number}} slot)
 
|Compare the current selected slot and the given slot to see if the items are the same. Returns true if they are the same, false if not.
 
|Compare the current selected slot and the given slot to see if the items are the same. Returns true if they are the same, false if not.
 
| 1.4
 
| 1.4
 
|-
 
|-
 
|{{type|boolean}} success
 
|{{type|boolean}} success
|[[turtle.drop]]([<nowiki></nowiki>{{type|int}} count])
+
|[[turtle.drop]]([<nowiki></nowiki>{{type|number}} count])
|Drops all items in the selected slot, or specified, drops ''count'' items.<br />[>= 1.4 only:] If there is a inventory on the side (i.e in front of the turtle) it will try to place into the inventory, returning false if the inventory is full.
+
|Drops all items in the selected slot, or specified, drops <var>count</var> items.<br />[>= 1.4 only:] If there is a inventory on the side (i.e in front of the turtle) it will try to place into the inventory, returning false if the inventory is full.
|
+
|?
 
|-
 
|-
 
|{{type|boolean}} success
 
|{{type|boolean}} success
|[[turtle.drop|turtle.dropUp]]([<nowiki></nowiki>{{type|int}} count])
+
|[[turtle.dropUp]]([<nowiki></nowiki>{{type|number}} count])
|Drops all items in the selected slot, or specified, drops ''count'' items.<br />[>= 1.4 only:] If there is a inventory on the side (i.e above the turtle) it will try to place into the inventory, returning false if the inventory is full.  
+
|Drops all items in the selected slot, or specified, drops <var>count</var> items.<br />[>= 1.4 only:] If there is a inventory on the side (i.e above the turtle) it will try to place into the inventory, returning false if the inventory is full.  
|
+
|1.4
 
|-
 
|-
 
|{{type|boolean}} success
 
|{{type|boolean}} success
|[[turtle.drop|turtle.dropDown]]([<nowiki></nowiki>{{type|int}} count])
+
|[[turtle.dropDown]]([<nowiki></nowiki>{{type|number}} count])
|Drops all items in the selected slot, or specified, drops ''count'' items.<br />[>= 1.4 only:] If there is a inventory on the side (i.e below the turtle) it will try to place into the inventory, returning false if the inventory is full. If above a furnace, will place item in the top slot.
+
|Drops all items in the selected slot, or specified, drops <var>count</var> items.<br />[>= 1.4 only:] If there is a inventory on the side (i.e below the turtle) it will try to place into the inventory, returning false if the inventory is full. If above a furnace, will place item in the top slot.
|
+
|1.4
 
|-
 
|-
 
|{{type|boolean}} success
 
|{{type|boolean}} success
|[[turtle.suck]]()
+
|[[turtle.suck]]([<nowiki></nowiki>{{type|number}} amount])
|Picks up an item stack of any number, from the ground or an inventory in front of the turtle, then places it in the selected slot. If the turtle can't pick up the item, the function returns false.
+
|Picks up an item stack of any number, from the ground or an inventory in front of the turtle, then places it in the selected slot. If the turtle can't pick up the item, the function returns false. <var>amount</var> parameter requires ComputerCraft 1.6 or later.
 
| 1.4
 
| 1.4
 
|-
 
|-
 
|{{type|boolean}} success
 
|{{type|boolean}} success
|[[turtle.suck|turtle.suckUp]]()
+
|[[turtle.suckUp]]([<nowiki></nowiki>{{type|number}} amount])
|Picks up an item stack of any number, from the ground or an inventory above the turtle, then places it in the selected slot. If the turtle can't pick up the item, the function returns false.
+
|Picks up an item stack of any number, from the ground or an inventory above the turtle, then places it in the selected slot. If the turtle can't pick up the item, the function returns false. <var>amount</var> parameter requires ComputerCraft 1.6 or later.
 
| 1.4
 
| 1.4
 
|-
 
|-
 
|{{type|boolean}} success
 
|{{type|boolean}} success
|[[turtle.suck|turtle.suckDown]]()
+
|[[turtle.suckDown]]([<nowiki></nowiki>{{type|number}} amount])
|Picks up an item stack of any number, from the ground or an inventory below the turtle, then places it in the selected slot. If the turtle can't pick up the item, the function returns false.
+
|Picks up an item stack of any number, from the ground or an inventory below the turtle, then places it in the selected slot. If the turtle can't pick up the item, the function returns false. <var>amount</var> parameter requires ComputerCraft 1.6 or later.
 
| 1.4
 
| 1.4
 
|-
 
|-
 
|{{type|boolean}} success
 
|{{type|boolean}} success
|[[turtle.refuel]]([<nowiki></nowiki>{{type|int}} quantity])
+
|[[turtle.refuel]]([<nowiki></nowiki>{{type|number}} quantity])
 
|If the current selected slot contains a fuel item, it will consume it to give the turtle the ability to move.<br />Added in 1.4 and is only needed in needfuel mode. If the current slot doesn't contain a fuel item, it returns false. Fuel values for different items can be found at [[Turtle.refuel#Fuel_Values]]. If a quantity is specified, it will refuel only up to that many items, otherwise, it will consume all the items in the slot.
 
|If the current selected slot contains a fuel item, it will consume it to give the turtle the ability to move.<br />Added in 1.4 and is only needed in needfuel mode. If the current slot doesn't contain a fuel item, it returns false. Fuel values for different items can be found at [[Turtle.refuel#Fuel_Values]]. If a quantity is specified, it will refuel only up to that many items, otherwise, it will consume all the items in the slot.
 
| 1.4
 
| 1.4
 
|-
 
|-
|{{type|int}} fuel
+
|{{type|number}} fuel
 
|[[turtle.getFuelLevel]]()
 
|[[turtle.getFuelLevel]]()
|Returns the current fuel level of the turtle, this is the number of blocks the turtle can move.<br />If turtleNeedFuel = 0 then it returns "unlimited".
+
|Returns the current fuel level of the turtle, this is the number of blocks the turtle can move.<br />If <var>turtleNeedFuel = 0</var> then it returns <var>"unlimited"</var>.
 
| 1.4
 
| 1.4
 +
|-
 +
|{{type|number}} fuel
 +
|[[turtle.getFuelLimit]]()
 +
|Returns the maximum amount of fuel a turtle can store - by default, 20,000 for regular turtles, 100,000 for advanced.<br />If <var>turtleNeedFuel = 0</var> then it returns <var>"unlimited"</var>.
 +
| 1.6
 
|-
 
|-
 
|{{type|boolean}} success
 
|{{type|boolean}} success
|[[turtle.transferTo]]({{type|int}} slot [, {{type|int}} quantity])
+
|[[turtle.transferTo]]({{type|number}} slot [, {{type|number}} quantity])
|Transfers ''quantity'' items from the selected slot to ''slot''. If ''quantity'' isn't specified, will attempt to transfer everything in the selected slot to ''slot''.
+
|Transfers <var>quantity</var> items from the selected slot to <var>slot</var>. If <var>quantity</var> isn't specified, will attempt to transfer everything in the selected slot to <var>slot</var>.
 
| 1.45
 
| 1.45
 
|}
 
|}
 
Trivia:
 
During the 1.4 beta, turtle.getFuelLevel() in softcore(that is now turtleneedsfuel = 0) returned 9000.
 
 
[[Category:APIs]]
 
[[Category:APIs]]

Latest revision as of 10:26, 24 October 2018

The Turtle API is used to work with your Turtles.

Key

Color Turtles that can perform this
White All
Green Crafty
Yellow Mining, Felling, Digging, Farming
Red Any tool

API

Return Method name Description Min version
boolean success turtle.craft(number quantity) Craft items using ingredients anywhere in the turtle's inventory and place results in the active slot. If a quantity is specified, it will craft only up to that many items, otherwise, it will craft as many of the items as possible. 1.4
boolean success turtle.forward() Try to move the turtle forward ?
boolean success turtle.back() Try to move the turtle backward ?
boolean success turtle.up() Try to move the turtle up ?
boolean success turtle.down() Try to move the turtle down ?
boolean success turtle.turnLeft() Turn the turtle left ?
boolean success turtle.turnRight() Turn the turtle right ?
boolean success turtle.select(number slotNum) Make the turtle select slot slotNum (1 is top left, 16 (9 in 1.33 and earlier) is bottom right) ?
number slot turtle.getSelectedSlot() Indicates the currently selected inventory slot 1.6
number count turtle.getItemCount([number slotNum]) Counts how many items are in the currently selected slot or, if specified, slotNum slot ?
number count turtle.getItemSpace([number slotNum]) Counts how many remaining items you need to fill the stack in the currently selected slot or, if specified, slotNum slot ?
table data turtle.getItemDetail([number slotNum]) Returns the ID string, count and damage values of currently selected slot or, if specified, slotNum slot 1.64
boolean success turtle.equipLeft() Attempts to equip an item in the current slot to the turtle's left side, switching the previously equipped item back into the inventory 1.6
boolean success turtle.equipRight() Attempts to equip an item in the current slot to the turtle's right side, switching the previously equipped item back into the inventory 1.6
boolean success turtle.attack([string toolSide]) Attacks in front of the turtle. 1.4
boolean success turtle.attackUp([string toolSide]) Attacks above the turtle. 1.4
boolean success turtle.attackDown([string toolSide]) Attacks under the turtle. 1.4
boolean success turtle.dig([string toolSide]) Breaks the block in front. With hoe: tills the dirt in front of it. ?
boolean success turtle.digUp([string toolSide]) Breaks the block above. ?
boolean success turtle.digDown([string toolSide]) Breaks the block below. With hoe: tills the dirt beneath the space below it. ?
boolean success turtle.place([string signText]) Places a block of the selected slot in front. Engrave signText on signs if provided. Collects water or lava if the currently selected slot is an empty bucket. 1.4
boolean success turtle.placeUp() Places a block of the selected slot above. Collects water or lava if the currently selected slot is an empty bucket. ?
boolean success turtle.placeDown() Places a block of the selected slot below. Collects water or lava if the currently selected slot is an empty bucket. ?
boolean result turtle.detect() Detects if there is a block in front. Does not detect mobs. ?
boolean result turtle.detectUp() Detects if there is a block above ?
boolean result turtle.detectDown() Detects if there is a block below ?
boolean success, table data/string error message turtle.inspect() Returns the ID string and metadata of the block in front of the Turtle 1.64
boolean success, table data/string error message turtle.inspectUp() Returns the ID string and metadata of the block above the Turtle 1.64
boolean success, table data/string error message turtle.inspectDown() Returns the ID string and metadata of the block below the Turtle 1.64
boolean result turtle.compare() Detects if the block in front is the same as the one in the currently selected slot 1.31
boolean result turtle.compareUp() Detects if the block above is the same as the one in the currently selected slot ?
boolean result turtle.compareDown() Detects if the block below is the same as the one in the currently selected slot ?
boolean result turtle.compareTo(number slot) Compare the current selected slot and the given slot to see if the items are the same. Returns true if they are the same, false if not. 1.4
boolean success turtle.drop([number count]) Drops all items in the selected slot, or specified, drops count items.
[>= 1.4 only:] If there is a inventory on the side (i.e in front of the turtle) it will try to place into the inventory, returning false if the inventory is full.
?
boolean success turtle.dropUp([number count]) Drops all items in the selected slot, or specified, drops count items.
[>= 1.4 only:] If there is a inventory on the side (i.e above the turtle) it will try to place into the inventory, returning false if the inventory is full.
1.4
boolean success turtle.dropDown([number count]) Drops all items in the selected slot, or specified, drops count items.
[>= 1.4 only:] If there is a inventory on the side (i.e below the turtle) it will try to place into the inventory, returning false if the inventory is full. If above a furnace, will place item in the top slot.
1.4
boolean success turtle.suck([number amount]) Picks up an item stack of any number, from the ground or an inventory in front of the turtle, then places it in the selected slot. If the turtle can't pick up the item, the function returns false. amount parameter requires ComputerCraft 1.6 or later. 1.4
boolean success turtle.suckUp([number amount]) Picks up an item stack of any number, from the ground or an inventory above the turtle, then places it in the selected slot. If the turtle can't pick up the item, the function returns false. amount parameter requires ComputerCraft 1.6 or later. 1.4
boolean success turtle.suckDown([number amount]) Picks up an item stack of any number, from the ground or an inventory below the turtle, then places it in the selected slot. If the turtle can't pick up the item, the function returns false. amount parameter requires ComputerCraft 1.6 or later. 1.4
boolean success turtle.refuel([number quantity]) If the current selected slot contains a fuel item, it will consume it to give the turtle the ability to move.
Added in 1.4 and is only needed in needfuel mode. If the current slot doesn't contain a fuel item, it returns false. Fuel values for different items can be found at Turtle.refuel#Fuel_Values. If a quantity is specified, it will refuel only up to that many items, otherwise, it will consume all the items in the slot.
1.4
number fuel turtle.getFuelLevel() Returns the current fuel level of the turtle, this is the number of blocks the turtle can move.
If turtleNeedFuel = 0 then it returns "unlimited".
1.4
number fuel turtle.getFuelLimit() Returns the maximum amount of fuel a turtle can store - by default, 20,000 for regular turtles, 100,000 for advanced.
If turtleNeedFuel = 0 then it returns "unlimited".
1.6
boolean success turtle.transferTo(number slot [, number quantity]) Transfers quantity items from the selected slot to slot. If quantity isn't specified, will attempt to transfer everything in the selected slot to slot. 1.45