Package io.github.thebusybiscuit.slimefun4.api.items.virtual

Interface VirtualItemHandler

All Superinterfaces:

ItemHandler

public interface VirtualItemHandler
extends ItemHandler

A hook for virtual or proxy items whose behavior cannot be fully expressed by the ItemStack's visible Material.

Implementations are expected to keep all hot-path methods cheap. They should only inspect compact metadata that was precomputed when the virtual item was created.

Register this handler on a SlimefunItem via SlimefunItem.addItemHandler(ItemHandler...).

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static enum	VirtualItemHandler.AdmissionResult	A tri-state admission result.
static enum	VirtualItemHandler.ComparisonResult	A tri-state comparison result.
static enum	VirtualItemHandler.ConsumeContext	The context in which a stack is consumed.
static enum	VirtualItemHandler.InventoryContext	The context in which a stack is inserted into an inventory.
static final record	VirtualItemHandler.ItemResult	A handled value result for operations that replace a stack.
static enum	VirtualItemHandler.MatchContext	The context in which two stacks are being compared.
static enum	VirtualItemHandler.RemainderContext	The context in which a crafting remainder is resolved.

Method Summary

Modifier and Type	Method	Description
default VirtualItemHandler.AdmissionResult	allows(org.bukkit.inventory.ItemStack item, VirtualItemHandler.InventoryContext context)	Decide whether a virtual stack may enter an empty slot in a given context.
default VirtualItemHandler.ItemResult	consume(org.bukkit.inventory.ItemStack item, int amount, boolean replaceConsumables, VirtualItemHandler.ConsumeContext context)	Consume an amount from a stack.
default Class<? extends ItemHandler>	getIdentifier()	This method returns the identifier for this ItemHandler.
default int	getMaxStackSize(org.bukkit.inventory.ItemStack item, VirtualItemHandler.InventoryContext context, int defaultMaxStackSize)	Resolve the effective max stack size for the given stack.
default VirtualItemHandler.ItemResult	getRemainder(org.bukkit.inventory.ItemStack item, VirtualItemHandler.RemainderContext context)	Resolve the remainder created when a stack is consumed for a crafting operation.
default boolean	isVirtualItem(org.bukkit.inventory.ItemStack item)	This should be a very cheap check that determines whether the given stack belongs to this virtual item system.
default VirtualItemHandler.ComparisonResult	matches(org.bukkit.inventory.ItemStack left, org.bukkit.inventory.ItemStack right, VirtualItemHandler.MatchContext context)	Compare two stacks in a given context.
default VirtualItemHandler.ComparisonResult	matchesPredicate(org.bukkit.inventory.ItemStack item, Predicate<org.bukkit.inventory.ItemStack> predicate, VirtualItemHandler.MatchContext context)	Compare a stack against a recipe predicate.

Methods inherited from interface io.github.thebusybiscuit.slimefun4.api.items.ItemHandler

validate

Method Details

getIdentifier

@Nonnull
default Class<? extends ItemHandler> getIdentifier()

Description copied from interface: ItemHandler

This method returns the identifier for this ItemHandler. We use a Class identifier to group Item Handlers together.

Specified by:

getIdentifier in interface ItemHandler

Returns:

The Class identifier for this ItemHandler

isVirtualItem

default boolean isVirtualItem(@Nullable
 org.bukkit.inventory.ItemStack item)

This should be a very cheap check that determines whether the given stack belongs to this virtual item system.

Parameters:

item - The stack to inspect

Returns:

Whether this stack should be handled by this hook

matches

@Nonnull
default VirtualItemHandler.ComparisonResult matches(@Nullable
 org.bukkit.inventory.ItemStack left,
 @Nullable
 org.bukkit.inventory.ItemStack right,
 @Nonnull
 VirtualItemHandler.MatchContext context)

Compare two stacks in a given context.

Parameters:

left - The left stack

right - The right stack

context - The comparison context

Returns:

The comparison result

matchesPredicate

@Nonnull
default VirtualItemHandler.ComparisonResult matchesPredicate(@Nonnull
 org.bukkit.inventory.ItemStack item,
 @Nonnull
 Predicate<org.bukkit.inventory.ItemStack> predicate,
 @Nonnull
 VirtualItemHandler.MatchContext context)

Compare a stack against a recipe predicate.

Parameters:

item - The stack to inspect

predicate - The target predicate

context - The comparison context

Returns:

The comparison result

getMaxStackSize

default int getMaxStackSize(@Nonnull
 org.bukkit.inventory.ItemStack item,
 @Nonnull
 VirtualItemHandler.InventoryContext context,
 int defaultMaxStackSize)

Resolve the effective max stack size for the given stack.

Parameters:

item - The stack to inspect

context - The insertion context

defaultMaxStackSize - The original max stack size

Returns:

The effective max stack size

allows

@Nonnull
default VirtualItemHandler.AdmissionResult allows(@Nonnull
 org.bukkit.inventory.ItemStack item,
 @Nonnull
 VirtualItemHandler.InventoryContext context)

Decide whether a virtual stack may enter an empty slot in a given context.

Parameters:

item - The stack to inspect

context - The insertion context

Returns:

The admission result

consume

@Nonnull
default VirtualItemHandler.ItemResult consume(@Nonnull
 org.bukkit.inventory.ItemStack item,
 int amount,
 boolean replaceConsumables,
 @Nonnull
 VirtualItemHandler.ConsumeContext context)

Consume an amount from a stack.

Parameters:

item - The original stack

amount - The amount to consume

replaceConsumables - Whether consumables should be replaced

context - The consume context

Returns:

The replacement result

getRemainder

@Nonnull
default VirtualItemHandler.ItemResult getRemainder(@Nonnull
 org.bukkit.inventory.ItemStack item,
 @Nonnull
 VirtualItemHandler.RemainderContext context)

Resolve the remainder created when a stack is consumed for a crafting operation.

Parameters:

item - The consumed stack

context - The crafting context

Returns:

The remainder result