Package net.neoforged.neoforge.transfer.access

Interface ItemAccess

All Known Implementing Classes:

HandlerItemAccess, InfiniteMaterialsItemAccess, OneByOneItemAccess, PlayerItemAccess, StackItemAccess

public interface ItemAccess

Provides access to an item storage location, like a slot in an inventory or a player's hand, such that the current item resource and amount can be read, and the stored item can be changed.

This interface is primarily used as the context type C for item capabilities. This allows the returned capability instance to modify the current item or even swap out the item entirely, for example to replace an empty bucket by a filled bucket. Use the getCapability(ItemCapability) method to query a capability for the item referenced by an item access.

Method Summary

Modifier and Type	Method	Description
default int	exchange(ItemResource newResource, int amount, TransactionContext transaction)	Exchanges up to the given amount of the the current resource with another.
int	extract(ItemResource resource, int amount, TransactionContext transaction)	Extracts up to the given amount of an item resource from the accessed location.
static ItemAccess	forHandlerIndex(ResourceHandler<ItemResource> handler, int index)	Creates an item access instance for a specific slot of an item resource handler, with any overflow being sent to the rest of the handler.
static ItemAccess	forHandlerIndexStrict(ResourceHandler<ItemResource> handler, int index)	Creates an item access instance for a specific slot of an item resource handler.
static ItemAccess	forInfiniteMaterials(Player player, ItemStack contents)	Creates an item access instance for a player with infinite materials, i.e. in creative mode.
static ItemAccess	forPlayerCursor(Player player, AbstractContainerMenu menu)	Creates an item access instance for a player's cursor in a menu.
static ItemAccess	forPlayerInteraction(Player player, InteractionHand hand)	Creates an item access instance for interaction with a player's hand.
static ItemAccess	forPlayerSlot(Player player, int slot)	Creates an item access instance for a specific slot of a player.
static ItemAccess	forStack(ItemStack stack)	Creates an item access instance that will mutate a stack directly, possibly changing the components and the count, but never the underlying Item as it's final.
int	getAmount()	Returns the currently stored amount of the current resource.
default <T> @Nullable T	getCapability(ItemCapability<T,ItemAccess> capability)	Retrieves a capability from this item location.
ItemResource	getResource()	Returns the currently stored item resource.
int	insert(ItemResource resource, int amount, TransactionContext transaction)	Inserts up to the given amount of an item resource into the accessed location.
default ItemAccess	oneByOne()	Creates a wrapper around this access that allows access to a single item at the time.

Method Details

forPlayerInteraction

static ItemAccess forPlayerInteraction(Player player,
 InteractionHand hand)

Creates an item access instance for interaction with a player's hand.

In creative mode, forInfiniteMaterials(Player, ItemStack) is used with the hand stack. Otherwise, forPlayerSlot(net.minecraft.world.entity.player.Player, int) with the hand slot is used. This matches the behavior of ItemUtils.createFilledResult(net.minecraft.world.item.ItemStack, net.minecraft.world.entity.player.Player, net.minecraft.world.item.ItemStack, boolean).

forInfiniteMaterials

static ItemAccess forInfiniteMaterials(Player player,
 ItemStack contents)

Creates an item access instance for a player with infinite materials, i.e. in creative mode.

The passed stack serves as a reference for the contents of the referenced location, and is never modified. Any insertion is always accepted, but only one item is actually added to the player's inventory, and only if the player does not already have the item. This matches the behavior of ItemUtils.createFilledResult(net.minecraft.world.item.ItemStack, net.minecraft.world.entity.player.Player, net.minecraft.world.item.ItemStack, boolean).

See Also:

• the recommended method for player interaction

forPlayerCursor

static ItemAccess forPlayerCursor(Player player,
 AbstractContainerMenu menu)

Creates an item access instance for a player's cursor in a menu.

forPlayerSlot

static ItemAccess forPlayerSlot(Player player,
 int slot)

Creates an item access instance for a specific slot of a player.

forHandlerIndex

static ItemAccess forHandlerIndex(ResourceHandler<ItemResource> handler,
 int index)

Creates an item access instance for a specific slot of an item resource handler, with any overflow being sent to the rest of the handler.

Overflow on insertion will be sent to the rest of the handler via the slotless insert method. If this is not desired, use the forHandlerIndexStrict(net.neoforged.neoforge.transfer.ResourceHandler<net.neoforged.neoforge.transfer.item.ItemResource>, int) method instead.

forHandlerIndexStrict

static ItemAccess forHandlerIndexStrict(ResourceHandler<ItemResource> handler,
 int index)

Creates an item access instance for a specific slot of an item resource handler.

To send overflow on insertion to the rest of the handler, use the forHandlerIndex(net.neoforged.neoforge.transfer.ResourceHandler<net.neoforged.neoforge.transfer.item.ItemResource>, int) method instead.

forStack

static ItemAccess forStack(ItemStack stack)

Creates an item access instance that will mutate a stack directly, possibly changing the components and the count, but never the underlying Item as it's final.

This can be used when it is known that the underlying Item will not change.

Throws:

IllegalArgumentException - if the stack is empty

oneByOne

@NonExtendable
default ItemAccess oneByOne()

Creates a wrapper around this access that allows access to a single item at the time.

getCapability

@NonExtendable
default <T> @Nullable T getCapability(ItemCapability<T,ItemAccess> capability)

Retrieves a capability from this item location.

getResource

ItemResource getResource()

Returns the currently stored item resource.

getAmount

int getAmount()

Returns the currently stored amount of the current resource.

The returned amount must be non-negative. If the stored resource is empty, the amount must be 0.

insert

int insert(ItemResource resource,
 int amount,
 TransactionContext transaction)

Inserts up to the given amount of an item resource into the accessed location.

If the inserted item is not stackable with the current item, it may be inserted in a place that is inaccessible by extract(net.neoforged.neoforge.transfer.item.ItemResource, int, net.neoforged.neoforge.transfer.transaction.TransactionContext), such as the player inventory.

Changes to the accessed location are made in the context of a transaction.

Parameters:

resource - The resource to insert. Must be non-empty.

amount - The maximum amount of the resource to insert. Must be non-negative.

transaction - The transaction that this operation is part of.

Returns:

The amount that was inserted. Between 0 (inclusive, nothing was inserted) and amount (inclusive, everything was inserted).

Throws:

IllegalArgumentException - If the resource is empty or the amount is negative. See also TransferPreconditions.checkNonEmptyNonNegative(net.neoforged.neoforge.transfer.resource.Resource, int) to help perform this check.

extract

int extract(ItemResource resource,
 int amount,
 TransactionContext transaction)

Extracts up to the given amount of an item resource from the accessed location.

Changes to the accessed location are made in the context of a transaction.

Parameters:

resource - The resource to extract. Must be non-empty.

amount - The maximum amount of the resource to extract. Must be non-negative.

transaction - The transaction that this operation is part of.

Returns:

The amount that was extracted. Between 0 (inclusive, nothing was extracted) and amount (inclusive, everything was extracted).

Throws:

IllegalArgumentException - If the resource is empty or the amount is negative. See also TransferPreconditions.checkNonEmptyNonNegative(net.neoforged.neoforge.transfer.resource.Resource, int) to help perform this check.

exchange

@NonExtendable
default int exchange(ItemResource newResource,
 int amount,
 TransactionContext transaction)

Exchanges up to the given amount of the the current resource with another.

That is, extract(net.neoforged.neoforge.transfer.item.ItemResource, int, net.neoforged.neoforge.transfer.transaction.TransactionContext) up to the given amount of the current item, and transactionally insert(net.neoforged.neoforge.transfer.item.ItemResource, int, net.neoforged.neoforge.transfer.transaction.TransactionContext) the same amount of the given resource instead.

Parameters:

newResource - The resource of the items after the exchange. Must be non-empty.

amount - The amount of items to exchange. Must be non-negative.

transaction - The transaction that this operation is part of.

Returns:

The amount that was exchanged. Between 0 (inclusive, nothing was exchanged) and amount (inclusive, everything was exchanged).

Throws:

IllegalArgumentException - If the given resource is empty or the amount is negative. See also TransferPreconditions.checkNonEmptyNonNegative(net.neoforged.neoforge.transfer.resource.Resource, int) to help perform this check.

IllegalStateException - If the current resource is empty.