Home

ITurtle API Documentation

Wrapper Methods

These are pretty self-explanitory, but it's still important to be explicit on what's new. The goal was to try to make sure these methods held the same vanilla functionality while also allowing new iterable functionality. All of the methods listed below retain the same name and parameter setup as their vanilla ComputerCraft counterpart, with the key difference that they now include an optional count parameter to allow for repetition of the same method.

The main exception to the parity are the return values you are given. Since each method is now capable of being called multiple times with a single function call, instead of returning a boolean and string to convey a single success, you are now given two number values to indicate failure count and total count of calls made. This would be the only change needed between vanilla CC code and ITurtle, otherwise any vanilla CC turtle program will work solely within the ITurtle module.

Note: ITurtle wraps the entire vanilla turtle library, including any default methods not listed below, so reference to turtle should not be needed (with the one exception listed above).

⮥ forward([count])

Move the turtle forward by a certain number of blocks.

Parameters

count? : number The number of steps you would like the turtle to take.
Default value is 1.

Returns

number | nil The amount of failed executions the turtle had.
number | nil The total amount of executions called.

⮥ back([count])

Move the turtle backwards by a certain number of blocks.

Parameters

count? : number The number of steps you would like the turtle to take.
Default value is 1.

Returns

number | nil The amount of failed executions the turtle had.
number | nil The total amount of executions called.

⮥ up([count])

Move the turtle up by a certain number of blocks.

Parameters

count? : number The number of steps you would like the turtle to take.
Default value is 1.

Returns

number | nil The amount of failed executions the turtle had.
number | nil The total amount of executions called.

⮥ down([count])

Move the turtle down by a certain number of blocks.

Parameters

count? : number The number of steps you would like the turtle to take.
Default value is 1.

Returns

number | nil The amount of failed executions the turtle had.
number | nil The total amount of executions called.

⮥ turnLeft([count])

Rotate the turtle left in increments of 90 degrees.

Parameters

count? : number The number of turns you would like the turtle to make.
Default value is 1.

Returns

number | nil The amount of failed executions the turtle had.
number | nil The total amount of executions called.

⮥ turnRight([count])

Rotate the turtle right in increments of 90 degrees.

Parameters

count? : number The number of turns you would like the turtle to make.
Default value is 1.

Returns

number | nil The amount of failed executions the turtle had.
number | nil The total amount of executions called.

⮥ dig([side [, count [, end_step]]])

Attempt to break a number of blocks in a line 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

side? : string The specific tool to use, should be "left" or "right".
Follows vanilla default behavior.
count? : number The number of blocks you would like the turtle to break.
Default value is 1.
end_step? : boolean Whether you want the turtle to take a final step after
breaking the last block. Default is false.

Returns

number | nil The amount of failed executions the turtle had.
number | nil The total amount of executions called.

⮥ digUp([side [, count [, end_step]]])

Attempt to break a number of blocks in a line above 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

side? : string The specific tool to use, should be "left" or "right".
Follows vanilla default behavior.
count? : number The number of blocks you would like the turtle to break.
Default value is 1.
end_step? : boolean Whether you want the turtle to take a final step after
breaking the last block. Default is false.

Returns

number | nil The amount of failed executions the turtle had.
number | nil The total amount of executions called.

⮥ digDown([side [, count [, end_step]]])

Attempt to break a number of blocks in a line below 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

side? : string The specific tool to use, should be "left" or "right".
Follows vanilla default behavior.
count? : number The number of blocks you would like the turtle to break.
Default value is 1.
end_step? : boolean Whether you want the turtle to take a final step after
breaking the last block. Default is false.

Returns

number | nil The amount of failed executions the turtle had.
number | nil The total amount of executions called.

⮥ attack([side [, count]])

Attack the entity in front of the turtle a certain number of times.

Parameters

side? : string The specific tool to use, should be "left" or "right".
Follows vanilla default behavior.
count? : number The number of times you would like the turtle to attack.
Default value is 1.

Returns

number | nil The amount of failed executions the turtle had.
number | nil The total amount of executions called.

⮥ attackUp([side [, count]])

Attack the entity above the turtle a certain number of times.

Parameters

side? : string The specific tool to use, should be "left" or "right".
Follows vanilla default behavior.
count? : number The number of times you would like the turtle to attack.
Default value is 1.

Returns

number | nil The amount of failed executions the turtle had.
number | nil The total amount of executions called.

⮥ attackDown([side [, count]])

Attack the entity below the turtle a certain number of times.

Parameters

side? : string The specific tool to use, should be "left" or "right".
Follows vanilla default behavior.
count? : number The number of times you would like the turtle to attack.
Default value is 1.

Returns

number | nil The amount of failed executions the turtle had.
number | nil The total amount of executions called.

New Methods

The remaining methods are all unique methods added to the ITurtle module.

This section covers a small list of extra, commonly used turtle maneuvers, as well as a few other miscellaneous QoL methods added. The latter section will cover the more complex looping methods to give developers a flexible system to compose specific looped instructions with.

⮥ turnAroundLeft([count [, dig]])

      Rotates the turtle left 90 degrees, moves forward for count steps, then
      rotates left again. If given a count of 0, the turtle will simply rotate 180
      degrees.

Parameters

count? : number The number of steps you would like the turtle to take.
Default value is 1.
dig? : boolean Whether the turtle should attempt to dig blocks in its way.
Default is false.

Returns

number | nil The amount of failed executions the turtle had.
number | nil The total amount of executions called.

⮥ turnAroundRight([count [, dig]])

      Rotates the turtle right 90 degrees, moves forward for count steps, then
      rotates right again. If given a count of 0, the turtle will simply rotate 180
      degrees.

Parameters

count? : number The number of steps you would like the turtle to take.
Default value is 1.
dig? : boolean Whether the turtle should attempt to dig blocks in its way.
Default is false.

Returns

number | nil The amount of failed executions the turtle had.
number | nil The total amount of executions called.

⮥ shiftLeft([count [, dig]])

Rotates the turtle left 90 degrees, moves forward for count steps, then
rotates back to the right to face the same direction it started with.

Parameters

count? : number The number of steps you would like the turtle to take.
Default value is 1.
dig? : boolean Whether the turtle should attempt to dig blocks in its way.
Default is false.

Returns

number | nil The amount of failed executions the turtle had.
number | nil The total amount of executions called.

⮥ shiftRight([count [, dig]])

Rotates the turtle right 90 degrees, moves forward for count steps, then
rotates back to the left to face the same direction it started with.

Parameters

count? : number The number of steps you would like the turtle to take.
Default value is 1.
dig? : boolean Whether the turtle should attempt to dig blocks in its way.
Default is false.

Returns

number | nil The amount of failed executions the turtle had.
number | nil The total amount of executions called.

⮥ registerDirection(direction)

      Allows the user to register the turtle's current facing direction. The turtle
      calibrates the orientation of its compass relative to the direction given,
      registering all four directions at once.

Parameters

direction : string The cardinal direction to register.
Should be "north", "south", "east", or "west".

Notes

      Any change to the turtle's rotation outside of the ITurtle API will cause its
      compass to become desynced (be careful when picking it up and placing it
      back down!). You can use the shell interface as a convenient way to
      ensure your turtle's compass remains calibrated.

Data will persist between loading. Saves to a file named .iturtle.dat in
the root directory.

⮥ unregisterDirection()

Allows the user to unregister the turtle's current facing direction, disabling
its internal compass entirely.

Notes

As of version 1.1, this will no longer delete .iturtle.dat.

⮥ setDirection(direction)

Rotates the robot to face the cardinal direction provided. Resulting
direction is based off of how registerDirection was calibrated.

Parameters

direction : string The cardinal direction to rotate to.
Should be "north", "south", "east", or "west".

Returns

bool | nil Whether the turtle ended up facing the direction requested.

⮥ getDirection()

Returns which cardnial direction the turtle is facing. Resulting direction
is based off of how registerDirection was calibrated.

Returns

string | nil The cardinal direction the turtle is currently facing.

⮥ blockData()

      Retrieves the table of information acquired by inspect directly without the
      boolean success result. Will always return a table, even if it's an empty
      one. Helpful for on the fly condition checks.

Returns

table Information about the block scanned, if any.

⮥ blockDataUp()

      Retrieves the table of information acquired by inspectUp directly without
      the boolean success result. Will always return a table, even if it's an
      empty one. Helpful for on the fly condition checks.

Returns

table Information about the block scanned, if any.

⮥ blockDataDown()

      Retrieves the table of information acquired by inspectDown directly
      without the boolean success result. Will always return a table, even
      if it's an empty one. Helpful for on the fly condition checks.

Returns

table Information about the block scanned, if any.

Navigation Methods

New in version 1.1, ITurtle now provides a few, very simple out-of-box navigation methods for instructing your turtles to specific points in the world with ease. It also provides a new location bookmarking system to give developers a way to save coordinates to a string, allowing it to be easily referenced later.

Most of the functions listed will require GPS data, so wireless modems will also be required to use them, as well as a registered (and correctly calibrated) compass. See registerDirection above regarding that.

Keep in mind, these are not pathfinding methods! They are simply a shorthand way to be able to move your turtle from one spot to another, they will do very little to adapt to their surroundings outside of deferring axes.

⮥ navigatePath([end_block [, path_block [, vert_block]]])

      Navigate a path pre-determined by the environment. The turtle will
      continue to moving forward, checking the block below it until one of the
      following conditions occur:

      1. The block detected has a facing property (and also matches
          path_block, if provided) in which the turtle turns to face the same
          direction and continues moving forward. Only works horizontally.
          NOTE: Does the opposite with glazed terracotta to coincide with
                     its texture, since it's reversed.
      2. The block detected matches the same as vert_block, in which the
          turtle will begin to travel upward until it detects a block above it. Then,
          it will continue to move forward.
      3. If it's traveling forward and there is no block detected beneath it, the
          turtle will begin to travel downward until it detects a block below it.
          Then, it continues forward.
      4. If the block detected is the same as end_block, the turtle will stop and
          the function will end.

Parameters

end_block? : string The block to detect to end the navigation.
Default value is "minecraft:chiseled_stone_bricks".
path_block? : function The block to dictate when a path turns.
Default value is any block with the facing property.
vert_block? : number The block to dictate when the path goes up.
Default value is "minecraft:soul_sand".

Returns

boolean Whether the navigation was successful or not.
string | nil The reason as to why the navigation was unsuccessful.
Can be: compass, fuel, or nil.

Notes

      Unlike the other navigation methods, this method is unable to calculate
      how much fuel is needed to get to its destination, so take caution with your
      fuel supply.

      Also, since the turtle must run a block check every time it moves, it will
      travel roughly ~12% slower than normal, but the innate complexity this
      method provides should outweigh that.

⮥ navigateLocal([x [, y [, z [, order]]]])

Will navigate the turtle a number of steps in each direction, relative to its
current rotation. Equivalent to the command /tp ^x ^y ^z.

Parameters

x? : number The distance to move sideways. Negative for left.
Default value is 0.
y? : number The distance to move vertically. Negative for down.
Default value is 0.
z? : number The distance to move forwards. Negative for back.
Default value is 0.
order? : string The initial order of axes to traverse. eg: "xzy" or "yz"
By default, will try to find the shortest axis each move.

Returns

boolean Whether the navigation was successful or not.
string | nil The reason as to why the navigation was unsuccessful.
Can be: fuel or nil.

Notes

This method will immediately end if the turtle does not have enough fuel
to reach its destination.

⮥ navigateToPoint(x, y, z [, order])

      Will navigate the turtle a specific coordinate in the world according to the
      turtle's GPS data and compass. Best used when data is aligned with
      Minecraft's default coordinates and directions.

Parameters

x : number The global x coordinate to move to.
y : number The global y coordinate to move to.
z : number The global z coordinate to move to.
order? : string The initial order of axes to traverse. eg: "xzy" or "yz"
By default, will try to find the shortest axis each move.

Returns

boolean Whether the navigation was successful or not.
string | nil The reason as to why the navigation was unsuccessful.
Can be: compass, gps, fuel, or nil.

Notes

This method will immediately end if the turtle does not have enough fuel
to reach its destination.

⮥ navigateToLocation(label [, order])

Identical to navigateToPoint, but will navigate the turtle a saved location
found in its database under the label passed.

Parameters

label : string The label of the saved location.
order? : string The initial order of axes to traverse. eg: "xzy" or "yz"
By default, will try to find the shortest axis each move.

Returns

boolean Whether the navigation was successful or not.
string | nil The reason as to why the navigation was unsuccessful.
Can be: compass, gps, fuel, or nil.

Notes

This method will immediately end if the turtle does not have enough fuel
to reach its destination.

⮥ registerLocation(label [, x, y, z])

      Saves a coordinate to a label to easily reference with navigateToLocation.
      If no coordinates are provided, will try to use the turtle's current location
      using its GPS data.

Parameters

label : string The label you want to save the location to.
x? : number The x coordinate to save. Must provide all or no axes.
y? : number The y coordinate to save. Must provide all or no axes.
z? : number The z coordinate to save. Must provide all or no axes.

Notes

Data will persist between loading. Saves to a file named .iturtle.dat in
the root directory.

⮥ unregisterLocation(label)

Deletes a saved location from the turtle's database.

Parameters

label : string The label you want to delete.

⮥ getLocation(label)

Retrieves the coordinates previously saved to a location label.

Parameters

label : string The label of the saved location.

Returns

number | nil The x coordinate of the location.
number | nil The y coordinate of the location.
number | nil The z coordinate of the location.

⮥ getAllLocations()

Retrieves the table containing every saved location in the turtle's database.

Returns

table The table of all saved locations.

Loop Methods

These are powerful functions that try to give a more plug and play feel to programming looping instructions for turtles. They offer a variety of ways to handle repeating entire functions.

NOTE: If any function passed as a parameter returns a truthy value, it will immediately end the loop it's in. This allows developers much more agency on ending loops early if they need to for whatever reason.

⮥ loop(fn [, stagingFn [, count]])

Loops a function. If a stagingFn function is provided, it will run in between
each call of fn but not after the final fn call.

Parameters

fn : function The function you want repeated.
stagingFn? : function The function you want to run in between each
execution of fn.
count? : number The number of loops you would like to make.
Default value is infinity.

Returns

number The number of what iteration the loop ended on.
any | nil The truthy value that caused the loop to stop early.

⮥ loopSwap(fn [, stagingFn [, count]])

      Works identical to loop, with the exception that any left or right
      instructions are swapped every iteration. This enables setups that
      require a zigzag instruction set where you need the turtle to mirror
      instructions in the opposite horizontal direction.

Parameters

fn : function The function you want repeated.
stagingFn? : function The function you want to run in between each
execution of fn.
count? : number The number of loops you would like to make.
Default value is infinity.

Returns

number The number of what iteration the loop ended on.
any | nil The truthy value that caused the loop to stop early.

⮥ loopUntil(fn [, stagingFn [, timeout]])

      A version of loop that instead of counting loops, the loop will end after a
      certain alotted time has passed. Once the timer is up, the loop will finish
      its currently running function and then end.

Parameters

fn : function The function you want repeated.
stagingFn? : function The function you want to run in between each
execution of fn.
timeout? : number The number of seconds you would like the loop to run
for. Rounds to the nearest 0.05 seconds. Default value is infinity.

Returns

number The number of what iteration the loop ended on.
any | nil The truthy value that caused the loop to stop early.

⮥ loopSwapUntil(fn [, stagingFn [, timeout]])

      Identical to loopUntil, but provides the same functionality as loopSwap
      where every left and right instruction are reversed every iteration to provide
      support for zigzag setups.

Parameters

fn : function The function you want repeated.
stagingFn? : function The function you want to run in between each
execution of fn.
timeout? : number The number of seconds you would like the loop to run
for. Rounds to the nearest 0.05 seconds. Default value is infinity.

Returns

number The number of what iteration the loop ended on.
any | nil The truthy value that caused the loop to stop early.

⮥ loopTimedOut([idx])

      Returns whether or not a loopUntil or loopSwapUntil timeout has
      triggered. The idx indicates which timer on the timeout stack to reference.
      Helpful for ending loops before they finish their current iteration.

      Note: The timeout stack only tracks active timers. A timer becomes
      inactive and gets popped off the stack once the loop it resides in ends,
      not when the timer times out.

Parameters

idx? : number The index of the timer you would like to check. Defaults to
the last timer on the timeout stack.

Returns

bool | nil Whether the timer has run out, if one exists.

⮥ loopTimeLeft([id])

Works similarly to loopTimedOut, but returns the amount of time left
remaining in the loop instead.

Parameters

idx? : number The index of the timer you would like to check. Defaults to
the last timer on the timeout stack.

Returns

number | nil The amount of time remaining in the timer, if one exists.

Wrapper Methods
- forward
- back
- up
- down
- turnLeft
- turnRight
- dig
- digUp
- digDown
- attack
- attackUp
- attackDown
New Methods
Navigation Methods
Loop Methods

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Home

ITurtle API Documentation

Wrapper Methods

New Methods

Navigation Methods

Loop Methods

Clone this wiki locally