Package net.fabricmc.fabric.api.transfer.v1.context

Interface ContainerItemContext

@Experimental public interface ContainerItemContext
A context that allows an item-queried Storage implementation to interact with its containing inventory, such as a player inventory or an emptying or filling machine. For example, it is what allows the Storage<FluidVariant> of a water bucket to replace the full bucket by an empty bucket on extraction. Such items that contain resources are often referred to as "container items".

When an item API requires a ContainerItemContext as context, it will generally be suitable to obtain a context instance with ofPlayerHand(net.minecraft.entity.player.PlayerEntity, net.minecraft.util.Hand) or ofPlayerCursor(net.minecraft.entity.player.PlayerEntity, net.minecraft.screen.ScreenHandler), and then use find(net.fabricmc.fabric.api.lookup.v1.item.ItemApiLookup<A, net.fabricmc.fabric.api.transfer.v1.context.ContainerItemContext>) to query an API instance.

When water is extracted from the Storage of a water bucket, this is how it interacts with the context:

  • The first step is to remove one water bucket item from the current slot, that is the slot that contains the water bucket.
  • The second step is to try to add one empty bucket item to the current slot, at the same position.
  • If that fails, the third step is to add the empty bucket item somewhere else in the inventory.
  • The water extraction can only proceed if both step 1, and step 2 or 3, succeed.
Before attempting to change the current item, the Storage implementation must of course check that the item in the current slot is still a water bucket.

A ContainerItemContext allows these operations to be performed, thanks to the following parts:

  • The main slot or current slot of the context, containing the item the API was queried for initially. In the example above, this is the slot containing the water bucket, used for steps 1 and 2.
  • An overflow insertion function, that can be used to insert items into the context's inventory when insertion into a specific slot fails. In our example above, this is the function used for step 3.
  • The context may also contain additional slots, accessible through getAdditionalSlots().

Implementors of item APIs can freely use these methods, but most will generally want to use the following convenience methods instead:

Experimental feature, we reserve the right to remove or change it without further notice. The transfer API is a complex addition, and we want to be able to correct possible design mistakes.

  • Method Details

    • ofPlayerHand

      static ContainerItemContext ofPlayerHand(net.minecraft.entity.player.PlayerEntity player, net.minecraft.util.Hand hand)
      Return a context for the passed player's hand. This is recommended for item use interactions.

    • ofPlayerCursor

      static ContainerItemContext ofPlayerCursor(net.minecraft.entity.player.PlayerEntity player, net.minecraft.screen.ScreenHandler screenHandler)
      Return a context for the passed player's cursor slot. This is recommended for screen handler click interactions.

    • ofPlayerSlot

      static ContainerItemContext ofPlayerSlot(net.minecraft.entity.player.PlayerEntity player, SingleSlotStorage<ItemVariant> slot)
      Return a context for a slot, with the passed player as fallback.

    • ofSingleSlot

      static ContainerItemContext ofSingleSlot(SingleSlotStorage<ItemVariant> slot)
      Return a context for a single slot, with no fallback.
      Parameters:
      slot - The main slot of the context.

    • withInitial

      static ContainerItemContext withInitial(net.minecraft.item.ItemStack initialContent)
      Return a context that can accept anything, and will accept (and destroy) any overflow items, with some initial content. This can typically be used to check if a stack provides an API, or simulate operations on the returned API, for example to simulate how much fluid could be extracted from the stack.

      Note that the stack can never be mutated by this function: its contents are copied directly.

    • withInitial

      static ContainerItemContext withInitial(ItemVariant initialVariant, long initialAmount)
      Return a context that can accept anything, and will accept (and destroy) any overflow items, with some initial variant and amount. This can typically be used to check if a variant provides an API, or simulate operations on the returned API, for example to simulate how much fluid could be extracted from the variant and amount.

    • find

      @Nullable default <A> A find(ItemApiLookup<A,ContainerItemContext> lookup)
      Try to find an API instance for the passed lookup and return it, or null if there is none. The API is queried for the current variant, if it's not blank.
      See Also:

    • getItemVariant

      default ItemVariant getItemVariant()
      Return the current item variant of this context, that is the variant in the slot of the context. If the result is non blank, getAmount() should be

    • getAmount

      default long getAmount()
      Return the current amount of getItemVariant() in the slot of the context.
      Throws:
      IllegalStateException - If the current variant is blank.

    • insert

      default long insert(ItemVariant itemVariant, long maxAmount, TransactionContext transaction)
      Try to insert some items into this context, prioritizing the main slot over the rest of the inventory.
      See Also:

    • extract

      default long extract(ItemVariant itemVariant, long maxAmount, TransactionContext transaction)
      Try to extract some items from this context's main slot.
      See Also:

    • exchange

      default long exchange(ItemVariant newVariant, long maxAmount, TransactionContext transaction)
      Try to exchange as many items as possible of the current variant with another variant. That is, extract the old variant, and insert the same amount of the new variant instead.
      Parameters:
      newVariant - The variant of the items after the conversion. May not be blank.
      maxAmount - The maximum amount of items to convert. May not be negative.
      transaction - The transaction this operation is part of.
      Returns:
      A nonnegative integer not greater than maxAmount: the amount that was transformed.

    • getMainSlot

      SingleSlotStorage<ItemVariant> getMainSlot()
      Return the main slot of this context.

    • insertOverflow

      long insertOverflow(ItemVariant itemVariant, long maxAmount, TransactionContext transactionContext)
      Try to insert items into this context, without prioritizing a specific slot, similar to PlayerInventory.offerOrDrop(net.minecraft.item.ItemStack). This should be used for insertion after insertion into the main slot failed. insert(net.fabricmc.fabric.api.transfer.v1.item.ItemVariant, long, net.fabricmc.fabric.api.transfer.v1.transaction.TransactionContext) can be used to insert into the main slot first, then send any overflow through this function.
      See Also:

    • getAdditionalSlots

      List<SingleSlotStorage<ItemVariant>> getAdditionalSlots()
      Get additional slots that may be available in this context. These may or may not include the main slot of this context, as it is not always practical to remove it from the list.
      Returns:
      An unmodifiable list containing additional slots of this context. If no additional slot is available, the list is empty.