Package dan200.computercraft.api.turtle

Interface ITurtleUpgrade

All Superinterfaces:
UpgradeBase
All Known Implementing Classes:
AbstractTurtleUpgrade
public interface ITurtleUpgrade extends UpgradeBase
The primary interface for defining an update for Turtles. A turtle update can either be a new tool, or a new peripheral.

Turtle upgrades are defined in two stages. First, one creates a ITurtleUpgrade subclass and corresponding TurtleUpgradeSerialiser instance, which are then registered in a Minecraft registry.

You then write a JSON file in your mod's data/ folder. This is then parsed when the world is loaded, and the upgrade automatically registered.

Example

Registering the upgrade serialiser

First, let's create a new class that implements ITurtleUpgrade. It is recommended to subclass AbstractTurtleUpgrade, as that provides a default implementation of most methods. 

public class ExampleTurtleUpgrade extends AbstractTurtleUpgrade {
    public ExampleTurtleUpgrade(ResourceLocation id, ItemStack stack) {
        super(id, TurtleUpgradeType.PERIPHERAL, stack);
    }
}

Now we must construct a new upgrade serialiser. In most cases, you can use one of the helper methods (e.g. TurtleUpgradeSerialiser.simpleWithCustomItem(BiFunction)), rather than defining your own implementation. 

public static final TurtleUpgradeSerialiser<ExampleTurtleUpgrade> EXAMPLE_TURTLE_UPGRADE = TurtleUpgradeSerialiser.simpleWithCustomItem(
    ExampleTurtleUpgrade::new
);
We now must register this upgrade serialiser. This is done the same way as you'd register blocks, items, or other Minecraft objects. The approach to do this will depend on mod-loader.

Fabric

@SuppressWarnings("unchecked")
var turtleUpgradeSerialisers = (Registry<TurtleUpgradeSerialiser<?>>) BuiltInRegistries.REGISTRY.get(TurtleUpgradeSerialiser.registryId().location());
Registry.register(turtleUpgradeSerialisers, new ResourceLocation(ExampleMod.MOD_ID, "example_turtle_upgrade"), ExampleMod.EXAMPLE_TURTLE_UPGRADE);

Forge

var modBus = FMLJavaModLoadingContext.get().getModEventBus();
modBus.addListener((RegisterEvent event) -> {
    event.register(TurtleUpgradeSerialiser.registryId(), new ResourceLocation(ExampleMod.MOD_ID, "example_turtle_upgrade"), () -> ExampleMod.EXAMPLE_TURTLE_UPGRADE);
});

Rendering the upgrade

Next, we need to register a model for our upgrade. This is done by registering a TurtleUpgradeModeller for your upgrade serialiser.

Fabric

FabricComputerCraftAPIClient.registerTurtleUpgradeModeller(ExampleMod.EXAMPLE_TURTLE_UPGRADE, TurtleUpgradeModeller.flatItem());

Forge

FabricComputerCraftAPIClient.registerTurtleUpgradeModeller(ExampleMod.EXAMPLE_TURTLE_UPGRADE, TurtleUpgradeModeller.flatItem());

Registering the upgrade itself

Upgrades themselves are loaded from datapacks when a level is loaded. In order to register our new upgrade, we must create a new JSON file at data/<my_mod>/computercraft/turtle_upgrades/<my_upgrade_id>.json. 
{
  "type": "examplemod:example_turtle_upgrade",
  "item": "minecraft:compass"
}
The "type" field points to the ID of the upgrade serialiser we've just registered, while the other fields are read by the serialiser itself. As our upgrade was defined with TurtleUpgradeSerialiser.simpleWithCustomItem(BiFunction), the "item" field will construct our upgrade with Items.COMPASS.

Rather than manually creating the file, it is recommended to data-generators to generate this file. This can be done with TurtleUpgradeDataProvider. 

public class TurtleDataProvider extends TurtleUpgradeDataProvider {
    public TurtleDataProvider(PackOutput output) {
        super(output);
    }

    @Override
    protected void addUpgrades(Consumer<Upgrade<TurtleUpgradeSerialiser<?>>> addUpgrade) {
        simpleWithCustomItem(
            new ResourceLocation(ExampleMod.MOD_ID, "example_turtle_upgrade"),
            ExampleMod.EXAMPLE_TURTLE_UPGRADE,
            Items.COMPASS
        ).add(addUpgrade);
    }
}
See Also:

  • Method Details

    • getType

      TurtleUpgradeType getType()
      Return whether this turtle adds a tool or a peripheral to the turtle.
      Returns:
      The type of upgrade this is.
      See Also:

    • createPeripheral

      default @Nullable 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 and will be passed as an argument to update(ITurtleAccess, TurtleSide). It 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

      default TurtleCommandResult useTool(ITurtleAccess turtle, TurtleSide side, TurtleVerb verb, net.minecraft.core.Direction 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.

      Conforming implementations should fire loader-specific events when using the tool, for instance Forge's AttackEntityEvent.

      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.

    • update

      default 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.

    • getPersistedData

      default net.minecraft.nbt.CompoundTag getPersistedData(net.minecraft.nbt.CompoundTag upgradeData)
      Get upgrade data that should be persisted when the turtle was broken.

      This method should be overridden when you don't need to store all upgrade data by default. For instance, if you store peripheral state in the upgrade data, which should be lost when the turtle is broken.

      Parameters:
      upgradeData - Data that currently stored for this upgrade
      Returns:
      Filtered version of this data.