Package dan200.computercraft.api.turtle

Interface ITurtleAccess

@NonExtendable public interface ITurtleAccess
The interface passed to turtle by turtles, providing methods that they can call.

This should not be implemented by your classes. Do not interact with turtles except via this interface and ITurtleUpgrade.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addFuel(int fuel)
    Increase the turtle's fuel level by the given amount.
    boolean
    consumeFuel(int fuel)
    Removes some fuel from the turtles fuel supply.
    MethodResult
    executeCommand(TurtleCommand command)
    Adds a custom command to the turtles command queue.
    int
    getColour()
    Get the colour of this turtle as a RGB number.
    net.minecraft.core.Direction
    getDirection()
    Returns the world direction the turtle is currently facing.
    int
    getFuelLevel()
    Get the current fuel level of this turtle.
    int
    getFuelLimit()
    Get the maximum amount of fuel a turtle can hold.
    net.minecraft.world.Container
    getInventory()
    Get the inventory of this turtle.
    net.minecraft.world.level.Level
    getLevel()
    Returns the world in which the turtle resides.
    @Nullable com.mojang.authlib.GameProfile
    getOwningPlayer()
    Get the player who owns this turtle, namely whoever placed it.
    @Nullable IPeripheral
    getPeripheral(TurtleSide side)
    Returns the peripheral created by the upgrade on the specified side of the turtle, if there is one.
    net.minecraft.core.BlockPos
    getPosition()
    Returns a vector containing the integer co-ordinates at which the turtle resides.
    int
    getSelectedSlot()
    Get the currently selected slot in the turtle's inventory.
    @Nullable ITurtleUpgrade
    getUpgrade(TurtleSide side)
    Returns the upgrade on the specified side of the turtle, if there is one.
    net.minecraft.core.component.DataComponentPatch
    getUpgradeData(TurtleSide side)
    Get an upgrade-specific NBT compound, which can be used to store arbitrary data.
    @Nullable UpgradeData<ITurtleUpgrade>
    getUpgradeWithData(TurtleSide side)
    Returns the upgrade on the specified side of the turtle, along with its update data.
    boolean
    isFuelNeeded()
    Determine whether this turtle will require fuel when performing actions.
    boolean
    isRemoved()
    Determine if this turtle has been removed.
    void
    playAnimation(TurtleAnimation animation)
    Start playing a specific animation.
    void
    setColour(int colour)
    Set the colour of the turtle to a RGB number.
    void
    setDirection(net.minecraft.core.Direction dir)
    Set the direction the turtle is facing.
    void
    setFuelLevel(int fuel)
    Set the fuel level to a new value.
    void
    setSelectedSlot(int slot)
    Set the currently selected slot in the turtle's inventory.
    void
    setUpgrade(TurtleSide side, @Nullable UpgradeData<ITurtleUpgrade> upgrade)
    Set the upgrade for a given side and its upgrade data.
    void
    setUpgradeData(TurtleSide side, net.minecraft.core.component.DataComponentPatch data)
    Update the upgrade-specific data.
    boolean
    teleportTo(net.minecraft.world.level.Level world, net.minecraft.core.BlockPos pos)
    Attempt to move this turtle to a new position.

  • Method Details

    • getLevel

      net.minecraft.world.level.Level getLevel()
      Returns the world in which the turtle resides.
      Returns:
      the world in which the turtle resides.

    • getPosition

      net.minecraft.core.BlockPos getPosition()
      Returns a vector containing the integer co-ordinates at which the turtle resides.
      Returns:
      a vector containing the integer co-ordinates at which the turtle resides.

    • isRemoved

      boolean isRemoved()
      Determine if this turtle has been removed.

      It's possible for a turtle to be removed while a TurtleCommand is executed, for instance if interacting with a block causes the turtle to be blown up. It's recommended you check the turtle is still present before trying to interact with it again.

      If a turtle has been removed getLevel() and getPosition() will continue to function as before. All other methods will fail.

      Returns:
      Whether this turtle has been removed.

    • teleportTo

      boolean teleportTo(net.minecraft.world.level.Level world, net.minecraft.core.BlockPos pos)
      Attempt to move this turtle to a new position.

      This will preserve the turtle's internal state, such as it's inventory, computer and upgrades. It should be used before playing a movement animation using playAnimation(TurtleAnimation).

      Parameters:
      world - The new world to move it to
      pos - The new position to move it to.
      Returns:
      Whether the movement was successful. It may fail if the block was not loaded or the block placement was cancelled.
      Throws:
      UnsupportedOperationException - When attempting to teleport on the client side.

    • getDirection

      net.minecraft.core.Direction getDirection()
      Returns the world direction the turtle is currently facing.
      Returns:
      The world direction the turtle is currently facing.
      See Also:

    • setDirection

      void setDirection(net.minecraft.core.Direction dir)
      Set the direction the turtle is facing. Note that this will not play a rotation animation, you will also need to call playAnimation(TurtleAnimation) to do so.
      Parameters:
      dir - The new direction to set. This should be on either the x or z axis (so north, south, east or west).
      See Also:

    • getSelectedSlot

      int getSelectedSlot()
      Get the currently selected slot in the turtle's inventory.
      Returns:
      An integer representing the current slot.
      See Also:

    • setSelectedSlot

      void setSelectedSlot(int slot)
      Set the currently selected slot in the turtle's inventory.
      Parameters:
      slot - The slot to set. This must be greater or equal to 0 and less than the inventory size. Otherwise no action will be taken.
      Throws:
      UnsupportedOperationException - When attempting to change the slot on the client side.
      See Also:

    • setColour

      void setColour(int colour)
      Set the colour of the turtle to a RGB number.
      Parameters:
      colour - The colour this turtle should be changed to. This should be a RGB colour between 0x000000 and 0xFFFFFF or -1 to reset to the default colour.
      See Also:

    • getColour

      int getColour()
      Get the colour of this turtle as a RGB number.
      Returns:
      The colour this turtle is. This will be a RGB colour between 0x000000 and 0xFFFFFF or -1 if it has no colour.
      See Also:

    • getOwningPlayer

      @Nullable com.mojang.authlib.GameProfile getOwningPlayer()
      Get the player who owns this turtle, namely whoever placed it.
      Returns:
      This turtle's owner.

    • getInventory

      net.minecraft.world.Container getInventory()
      Get the inventory of this turtle.

      Note: this inventory should only be accessed and modified on the server thread.

      Returns:
      This turtle's inventory

    • isFuelNeeded

      boolean isFuelNeeded()
      Determine whether this turtle will require fuel when performing actions.
      Returns:
      Whether this turtle needs fuel.
      See Also:

    • getFuelLevel

      int getFuelLevel()
      Get the current fuel level of this turtle.
      Returns:
      The turtle's current fuel level.
      See Also:

    • setFuelLevel

      void setFuelLevel(int fuel)
      Set the fuel level to a new value. It is generally preferred to use consumeFuel(int)} or addFuel(int) instead.
      Parameters:
      fuel - The new amount of fuel. This must be between 0 and the fuel limit.
      See Also:

    • getFuelLimit

      int getFuelLimit()
      Get the maximum amount of fuel a turtle can hold.
      Returns:
      The turtle's fuel limit.

    • consumeFuel

      boolean consumeFuel(int fuel)
      Removes some fuel from the turtles fuel supply. Negative numbers can be passed in to INCREASE the fuel level of the turtle.
      Parameters:
      fuel - The amount of fuel to consume.
      Returns:
      Whether the turtle was able to consume the amount of fuel specified. Will return false if you supply a number greater than the current fuel level of the turtle. No fuel will be consumed if false is returned.
      Throws:
      UnsupportedOperationException - When attempting to consume fuel on the client side.

    • addFuel

      void addFuel(int fuel)
      Increase the turtle's fuel level by the given amount.
      Parameters:
      fuel - The amount to refuel with.
      Throws:
      UnsupportedOperationException - When attempting to refuel on the client side.

    • executeCommand

      MethodResult executeCommand(TurtleCommand command)
      Adds a custom command to the turtles command queue. Unlike peripheral methods, these custom commands will be executed on the main thread, so are guaranteed to be able to access Minecraft objects safely, and will be queued up with the turtles standard movement and tool commands. An issued command will return an unique integer, which will be supplied as a parameter to a "turtle_response" event issued to the turtle after the command has completed. Look at the lua source code for "rom/apis/turtle" for how to build a lua wrapper around this functionality.
      Parameters:
      command - An object which will execute the custom command when its point in the queue is reached
      Returns:
      The objects the command returned when executed. you should probably return these to the player unchanged if called from a peripheral method.
      Throws:
      UnsupportedOperationException - When attempting to execute a command on the client side.
      See Also:

    • playAnimation

      void playAnimation(TurtleAnimation animation)
      Start playing a specific animation. This will prevent other turtle commands from executing until it is finished.
      Parameters:
      animation - The animation to play.
      Throws:
      UnsupportedOperationException - When attempting to execute play an animation on the client side.
      See Also:

    • getUpgrade

      @Nullable ITurtleUpgrade getUpgrade(TurtleSide side)
      Returns the upgrade on the specified side of the turtle, if there is one.
      Parameters:
      side - The side to get the upgrade from.
      Returns:
      The upgrade on the specified side of the turtle, if there is one.
      See Also:

    • getUpgradeWithData

      @Nullable UpgradeData<ITurtleUpgrade> getUpgradeWithData(TurtleSide side)
      Returns the upgrade on the specified side of the turtle, along with its update data.
      Parameters:
      side - The side to get the upgrade from.
      Returns:
      The upgrade on the specified side of the turtle, along with its upgrade data, if there is one.
      See Also:

    • setUpgrade

      void setUpgrade(TurtleSide side, @Nullable UpgradeData<ITurtleUpgrade> upgrade)
      Set the upgrade for a given side and its upgrade data.
      Parameters:
      side - The side to set the upgrade on.
      upgrade - The upgrade to set, may be null to clear.
      See Also:

    • getPeripheral

      @Nullable IPeripheral getPeripheral(TurtleSide side)
      Returns the peripheral created by the upgrade on the specified side of the turtle, if there is one.
      Parameters:
      side - The side to get the peripheral from.
      Returns:
      The peripheral created by the upgrade on the specified side of the turtle, null if none exists.

    • getUpgradeData

      net.minecraft.core.component.DataComponentPatch getUpgradeData(TurtleSide side)
      Get an upgrade-specific NBT compound, which can be used to store arbitrary data.

      This will be persisted across turtle restarts and chunk loads, as well as being synced to the client. You can call setUpgrade(TurtleSide, UpgradeData) to modify it.

      Parameters:
      side - The side to get the upgrade data for.
      Returns:
      The upgrade-specific data.
      See Also:

    • setUpgradeData

      void setUpgradeData(TurtleSide side, net.minecraft.core.component.DataComponentPatch data)
      Update the upgrade-specific data.
      Parameters:
      side - The side to set the upgrade data for.
      data - The new upgrade data.
      See Also: