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

    • allowNbtUpdateAnimation

      default boolean allowNbtUpdateAnimation(PlayerEntity player, Hand hand, ItemStack oldStack, ItemStack newStack)
      When the NBT 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 NBT 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 NBT of the selected stack changes, block breaking progress is reset. This function is called when the NBT 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.

    • getAttributeModifiers

      default com.google.common.collect.Multimap<EntityAttribute,EntityAttributeModifier> getAttributeModifiers(ItemStack stack, EquipmentSlot slot)
      Return the attribute modifiers to apply when this stack is worn in a living entity equipment slot. Stack-aware version of Item.getAttributeModifiers(EquipmentSlot).

      Note that attribute modifiers are only updated when the stack changes, i.e. when ItemStack.areEqual(old, new) is false.

      Parameters:
      stack - the current stack
      slot - the equipment slot this stack is in
      Returns:
      the attribute modifiers

    • isSuitableFor

      default boolean isSuitableFor(ItemStack stack, BlockState state)
      Determines if mining with this item allows drops to be harvested from the specified block state. Stack-aware version of Item.isSuitableFor(BlockState).
      Parameters:
      stack - the current stack
      state - the block state of the targeted block
      Returns:
      true if drops can be harvested

    • 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

    • getFoodComponent

      @Nullable default @Nullable FoodComponent getFoodComponent(ItemStack stack)
      This is a stack-aware version of Item.getFoodComponent(). Note that simple food component can also be set via Item.Settings.food(FoodComponent). If you want to get a food component for a stack, is recommended to use the stack version of this method: FabricItemStack.getFoodComponent().
      Returns:
      this item's FoodComponent, or null if none was set

    • canBeEnchantedWith

      default boolean canBeEnchantedWith(ItemStack stack, 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

    • getIntrinsicEnchantments

      default it.unimi.dsi.fastutil.objects.Object2IntMap<Enchantment> getIntrinsicEnchantments(ItemStack stack)
      Returns a (stack-aware) map of intrinsic enchantments for this item. These enchantments have their usual gameplay effects, but do not produce glint or otherwise show on the item, and cannot be removed with a grindstone. For example, a mod that adds an electric multi-tool might want to give it a Silk Touch-like effect, without relying on the vanilla system.

      By default, having an intrinsic enchantment does not prevent the item from being enchanted with the same one by normal means. In such a case, only the highest level of the enchantment will be retained. To prevent the item from receiving certain enchantments, use canBeEnchantedWith(ItemStack, Enchantment, EnchantingContext).

      Parameters:
      stack - the current stack
      Returns:
      an immutable map from each intrinsic enchantment to its level
      See Also: