dan200.computercraft.api.turtle

## Interface ITurtleUpgrade

    public interface ITurtleUpgrade

The primary interface for defining an update for Turtles. A turtle update can either be a new tool, or a new peripheral.

See Also:
  `ComputerCraftAPI.registerTurtleUpgrade( dan200.computercraft.api.turtle.ITurtleUpgrade )`

### Method Summary

Methods
`IPeripheral` `createPeripheral(ITurtleAccess turtle, TurtleSide side)` Will only be called for peripheral upgrades.
`ItemStack` `getCraftingItem()` Return an item stack representing the type of item that a turtle must be crafted with to create a turtle which holds this upgrade.
`int` `getLegacyUpgradeID()` Gets a numerical identifier representing this type of turtle upgrade, for backwards compatibility with pre-1.76 worlds.
`<any>` `getModel(ITurtleAccess turtle, TurtleSide side)` Called to obtain the model to be used when rendering a turtle peripheral.
`TurtleUpgradeType` `getType()` Return whether this turtle adds a tool or a peripheral to the turtle.
`java.lang.String` `getUnlocalisedAdjective()` Return a String to describe this type of turtle in turtle item names.
`ResourceLocation` `getUpgradeID()` Gets a unique identifier representing this type of turtle upgrade.
`void` `update(ITurtleAccess turtle, TurtleSide side)` Called once per tick for each turtle which has the upgrade equipped.
`TurtleCommandResult` `useTool(ITurtleAccess turtle, TurtleSide side, TurtleVerb verb, EnumFacing direction)` Will only be called for Tool turtle.

### Method Detail

#### getUpgradeID

    ResourceLocation getUpgradeID()

Gets a unique identifier representing this type of turtle upgrade. eg: "computercraft:wireless_modem" or "my_mod:my_upgrade". You should use a unique resource domain to ensure this upgrade is uniquely identified. The turtle will fail registration if an already used ID is specified.

See Also:
  `ComputerCraftAPI.registerTurtleUpgrade( dan200.computercraft.api.turtle.ITurtleUpgrade )`

#### getLegacyUpgradeID

    int getLegacyUpgradeID()

Gets a numerical identifier representing this type of turtle upgrade, for backwards compatibility with pre-1.76 worlds. If your upgrade was not released for older ComputerCraft versions, you can return -1 here. The turtle will fail registration if an already used positive ID is specified.

See Also:
  `ComputerCraftAPI.registerTurtleUpgrade( dan200.computercraft.api.turtle.ITurtleUpgrade )`

#### getUnlocalisedAdjective

    java.lang.String getUnlocalisedAdjective()

Return a String to describe this type of turtle in turtle item names. Examples of built-in adjectives are "Wireless", "Mining" and "Crafty".

#### getType

    TurtleUpgradeType getType()

Return whether this turtle adds a tool or a peripheral to the turtle.

See Also:
  `for the differences between the two.`

#### getCraftingItem

    ItemStack getCraftingItem()

Return an item stack representing the type of item that a turtle must be crafted with to create a turtle which holds this upgrade. This item stack is also used to determine the upgrade given by turtle.equip()

#### createPeripheral

    IPeripheral createPeripheral(ITurtleAccess turtle,
                               TurtleSide side)

Will only be called for peripheral upgrades. Creates a peripheral for a turtle being placed using this upgrade. The peripheral created will be stored for the lifetime of the upgrade, will have update() called once-per-tick, and will be attached, detached and have methods called in the same manner as a Computer peripheral.

Parameters:
  `turtle` - Access to the turtle that the peripheral is being created for.
  `side` - Which side of the turtle (left or right) that the upgrade resides on.
Returns:
  The newly created peripheral. You may return null if this upgrade is a Tool and this method is not expected to be called.

#### useTool

    TurtleCommandResult useTool(ITurtleAccess turtle,
                              TurtleSide side,
                              TurtleVerb verb,
                              EnumFacing direction)

Will only be called for Tool turtle. Called when turtle.dig() or turtle.attack() is called by the turtle, and the tool is required to do some work.

Parameters:
  `turtle` - Access to the turtle that the tool resides on.
  `side` - Which side of the turtle (left or right) the tool resides on.
  `verb` - Which action (dig or attack) the turtle is being called on to perform.
  `direction` - Which world direction the action should be performed in, relative to the turtles position. This will either be up, down, or the direction the turtle is facing, depending on whether dig, digUp or digDown was called.
Returns:
  Whether the turtle was able to perform the action, and hence whether the turtle.dig() or turtle.attack() lua method should return true. If true is returned, the tool will perform a swinging animation. You may return null if this turtle is a Peripheral and this method is not expected to be called.

#### getModel

    <any> getModel(ITurtleAccess turtle,
                 TurtleSide side)

Called to obtain the model to be used when rendering a turtle peripheral.

Parameters:
  `turtle` - Access to the turtle that the upgrade resides on. This will be null when getting item models!
  `side` - Which side of the turtle (left or right) the upgrade resides on.
Returns:
  The model that you wish to be used to render your upgrade, and a transformation to apply to it. Returning a transformation of null has the same effect as the identify matrix.

#### update

    void update(ITurtleAccess turtle,
              TurtleSide side)

Called once per tick for each turtle which has the upgrade equipped.

Parameters:
  `turtle` - Access to the turtle that the upgrade resides on.
  `side` - Which side of the turtle (left or right) the upgrade resides on.