Package net.fabricmc.fabric.api.item.v1

Interface FabricItem

public interface FabricItem
General-purpose Fabric-provided extensions for Item subclasses.

Note: This interface is automatically implemented on all items via Mixin and interface injection.

Note to maintainers: Functions should only be added to this interface if they are general-purpose enough, to be evaluated on a case-by-case basis. Otherwise, they are better suited for more specialized APIs.

  • Method Details

    • allowComponentsUpdateAnimation

      default boolean allowComponentsUpdateAnimation(PlayerEntity player, Hand hand, ItemStack oldStack, ItemStack newStack)
      When the components of an item stack in the main hand or off hand changes, vanilla runs an "update animation". This function is called on the client side when the components or count of the stack has changed, but not the item, and returning false cancels this animation.
      Parameters:
      player - the current player; this may be safely cast to ClientPlayerEntity in client-only code
      hand - the hand; this function applies both to the main hand and the off hand
      oldStack - the previous stack, of this item
      newStack - the new stack, also of this item
      Returns:
      true to run the vanilla animation, false to cancel it.

    • allowContinuingBlockBreaking

      default boolean allowContinuingBlockBreaking(PlayerEntity player, ItemStack oldStack, ItemStack newStack)
      When the components of the selected stack changes, block breaking progress is reset. This function is called when the components of the selected stack has changed, and returning true allows the block breaking progress to continue.
      Parameters:
      player - the player breaking the block
      oldStack - the previous stack, of this item
      newStack - the new stack, also of this item
      Returns:
      true to allow continuing block breaking, false to reset the progress.

    • getRecipeRemainder

      default ItemStack getRecipeRemainder(ItemStack stack)
      Returns a leftover item stack after stack is consumed in a recipe. (This is also known as "recipe remainder".) For example, using a lava bucket in a furnace as fuel will leave an empty bucket.

      Here is an example for a recipe remainder that increments the item's damage. 

      
  if (stack.getDamage() < stack.getMaxDamage() - 1) {
  	ItemStack moreDamaged = stack.copy();
  	moreDamaged.setDamage(stack.getDamage() + 1);
  	return moreDamaged;
  }

  return ItemStack.EMPTY;

      This is a stack-aware version of Item.getRecipeRemainder().

      Note that simple item remainders can also be set via Item.Settings.recipeRemainder(Item).

      If you want to get a remainder for a stack, is recommended to use the stack version of this method: FabricItemStack.getRecipeRemainder().

      Parameters:
      stack - the consumed ItemStack
      Returns:
      the leftover item stack

    • canBeEnchantedWith

      default boolean canBeEnchantedWith(ItemStack stack, RegistryEntry<Enchantment> enchantment, EnchantingContext context)
      Determines if the item is allowed to receive an Enchantment. This can be used to manually override what enchantments a modded item is able to receive.

      For example, one might want a modded item to be able to receive Unbreaking, but not Mending, which cannot be achieved with the vanilla tag system alone. Alternatively, one might want to do the same thing with enchantments from other mods, which don't have a similar tag system in general.

      Note that this method is only called after the EnchantmentEvents.ALLOW_ENCHANTING event, and only if none of the listeners to that event override the result.

      Parameters:
      stack - the current stack
      enchantment - the enchantment to check
      context - the context in which the enchantment is being checked
      Returns:
      whether the enchantment is allowed to apply to the stack