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:

• Query which variant is currently in the main slot through getItemVariant(). It is important to check this before any operation, to make sure the item variant hasn't changed since the query.
• Query how much of the (non-blank) variant is in the inventory through getAmount().
• Extract some items from the main slot with extract(net.fabricmc.fabric.api.transfer.v1.item.ItemVariant, long, net.fabricmc.fabric.api.transfer.v1.transaction.TransactionContext). In the water bucket example, this can be used for step 1.
• Insert some items, either into the main slot if possible or the rest of the inventory otherwise, with insert(net.fabricmc.fabric.api.transfer.v1.item.ItemVariant, long, net.fabricmc.fabric.api.transfer.v1.transaction.TransactionContext). In the water bucket example, this can be used for steps 2 and 3.
• Exchange some of the current variant with another variant through exchange(net.fabricmc.fabric.api.transfer.v1.item.ItemVariant, long, net.fabricmc.fabric.api.transfer.v1.transaction.TransactionContext). In the water bucket example, this function can be used to combine steps 1, 2 and 3.

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 Summary

Modifier and Type	Method	Description
default long	exchange(ItemVariant newVariant, long maxAmount, TransactionContext transaction)	Try to exchange as many items as possible of the current variant with another variant.
default long	extract(ItemVariant itemVariant, long maxAmount, TransactionContext transaction)	Try to extract some items from this context's main slot.
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.
static ContainerItemContext	forCreativeInteraction(PlayerEntity player, ItemStack interactingStack)	Returns a context for creative interaction.
static ContainerItemContext	forPlayerInteraction(PlayerEntity player, Hand hand)	Returns a context for interaction with a player's hand.
@UnmodifiableView List<SingleSlotStorage<ItemVariant>>	getAdditionalSlots()	Get additional slots that may be available in this context.
default long	getAmount()	Return the current amount of getItemVariant() in the slot of the context.
default ItemVariant	getItemVariant()	Return the current item variant of this context, that is the variant in the slot of the context.
SingleSlotStorage<ItemVariant>	getMainSlot()	Return the main slot of this context.
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.
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).
static ContainerItemContext	ofPlayerCursor(PlayerEntity player, ScreenHandler screenHandler)	Return a context for the passed player's cursor slot.
static ContainerItemContext	ofPlayerHand(PlayerEntity player, Hand hand)	Return a context for the passed player's hand.
static ContainerItemContext	ofPlayerSlot(PlayerEntity player, SingleSlotStorage<ItemVariant> slot)	Return a context for a slot, with the passed player as fallback.
static ContainerItemContext	ofSingleSlot(SingleSlotStorage<ItemVariant> slot)	Return a context for a single slot, with no fallback.
static ContainerItemContext	withConstant(ItemVariant constantVariant, long constantAmount)	Return a context that always has some content, and will accept (and destroy) any overflow items.
static ContainerItemContext	withConstant(ItemStack constantContent)	Return a context that always has some content, and will accept (and destroy) any overflow items.
static ContainerItemContext	withInitial(ItemVariant initialVariant, long initialAmount)	Deprecated, for removal: This API element is subject to removal in a future version. Use withConstant(ItemVariant, long) instead.
static ContainerItemContext	withInitial(ItemStack initialContent)	Deprecated, for removal: This API element is subject to removal in a future version. Use withConstant(ItemStack) instead.

Method Details

forPlayerInteraction

static ContainerItemContext forPlayerInteraction(PlayerEntity player,
 Hand hand)

Returns a context for interaction with a player's hand. This is recommended for item use interactions.

In creative mode, forCreativeInteraction(net.minecraft.entity.player.PlayerEntity, net.minecraft.item.ItemStack) is used with the hand stack. Otherwise, ofPlayerHand(net.minecraft.entity.player.PlayerEntity, net.minecraft.util.Hand) is used. This matches the behavior of ItemUsage.exchangeStack(net.minecraft.item.ItemStack, net.minecraft.entity.player.PlayerEntity, net.minecraft.item.ItemStack, boolean).

forCreativeInteraction

static ContainerItemContext forCreativeInteraction(PlayerEntity player,
 ItemStack interactingStack)

Returns a context for creative interaction.

The stack will never be modified, and any updated stack will only be added to the player's inventory if the player's inventory doesn't already contain it. This matches the creative behavior of ItemUsage.exchangeStack(net.minecraft.item.ItemStack, net.minecraft.entity.player.PlayerEntity, net.minecraft.item.ItemStack, boolean).

ofPlayerHand

static ContainerItemContext ofPlayerHand(PlayerEntity player,
 Hand hand)

Return a context for the passed player's hand.

ofPlayerCursor

static ContainerItemContext ofPlayerCursor(PlayerEntity player,
 ScreenHandler screenHandler)

Return a context for the passed player's cursor slot. This is recommended for screen handler click interactions.

ofPlayerSlot

static ContainerItemContext ofPlayerSlot(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.

withConstant

static ContainerItemContext withConstant(ItemStack constantContent)

Return a context that always has some content, and will accept (and destroy) any overflow items. 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.

withConstant

static ContainerItemContext withConstant(ItemVariant constantVariant,
 long constantAmount)

Return a context that always has some content, and will accept (and destroy) any overflow items. 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 variant and amount.

withInitial

@Deprecated(forRemoval=true)
static ContainerItemContext withInitial(ItemStack initialContent)

Deprecated, for removal: This API element is subject to removal in a future version.

Use withConstant(ItemStack) instead.

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

@Deprecated(forRemoval=true)
static ContainerItemContext withInitial(ItemVariant initialVariant,
 long initialAmount)

Deprecated, for removal: This API element is subject to removal in a future version.

Use withConstant(ItemVariant, long) instead.

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:

• ItemApiLookup.find(net.minecraft.item.ItemStack, C)

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 not blank, getAmount() should be positive.

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:

• Storage.insert(T, long, net.fabricmc.fabric.api.transfer.v1.transaction.TransactionContext)

extract

default long extract(ItemVariant itemVariant,
 long maxAmount,
 TransactionContext transaction)

Try to extract some items from this context's main slot.

See Also:

• Storage.extract(T, long, net.fabricmc.fabric.api.transfer.v1.transaction.TransactionContext)

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 non-negative 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:

• Storage.insert(T, long, net.fabricmc.fabric.api.transfer.v1.transaction.TransactionContext)

getAdditionalSlots

@UnmodifiableView 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.