public interface Inventory extends Iterable<Inventory>, Nameable
Modifier and Type | Interface and Description |
---|---|
static interface |
Inventory.Builder
A Builder for Inventories based on
InventoryArchetype s. |
Modifier and Type | Method and Description |
---|---|
static Inventory.Builder |
builder()
Creates a new
Inventory.Builder to build an Inventory . |
boolean |
canFit(ItemStack stack)
Returns true if the entire stack can fit in this inventory.
|
int |
capacity()
The maximum number of stacks the Inventory can hold.
|
void |
clear()
Clears this inventory if it is clearable.
|
boolean |
contains(ItemStack stack)
Checks whether the stacks quantity or more of given stack is
contained in this Inventory.
|
boolean |
contains(ItemType type)
Checks for whether there is a stack in this Inventory with the given
ItemType.
|
boolean |
containsAny(ItemStack stack)
Checks whether the given stack is contained in this Inventory.
|
boolean |
containsInventory(Inventory inventory)
Returns true if the given inventory is a descendant of this one.
|
<T extends Inventory> |
first()
Return the first child inventory, effectively the same as
Inventory::iterator().next() but more convenient when we are
expecting a result set with only a single entry. |
InventoryArchetype |
getArchetype()
Creates an
InventoryArchetype based on this Inventory . |
<T extends InventoryProperty<?,?>> |
getInventoryProperty(Class<T> property)
Gets a property with the default key defined directly on this Inventory
if one is defined.
|
<T extends InventoryProperty<?,?>> |
getInventoryProperty(Inventory child,
Class<T> property)
Gets the property with the default key defined in this
inventory for the specified (immediate) sub-inventory.
|
int |
getMaxStackSize()
Returns the maximum size of any stack in this Inventory.
|
PluginContainer |
getPlugin()
Returns the
PluginContainer who built this inventory. |
<T extends InventoryProperty<?,?>> |
getProperties(Class<T> property)
Gets all properties of the specified type defined directly on this
Inventory.
|
<T extends InventoryProperty<?,?>> |
getProperties(Inventory child,
Class<T> property)
Returns all properties matching the supplied type defined in
this inventory for the specified (immediate) sub-inventory.
|
<T extends InventoryProperty<?,?>> |
getProperty(Class<T> property,
Object key)
Gets a property with the specified key defined directly on this Inventory
if one is defined.
|
<T extends InventoryProperty<?,?>> |
getProperty(Inventory child,
Class<T> property,
Object key)
Gets the property with the specified key defined in this
inventory for the specified (immediate) sub-inventory.
|
boolean |
hasChildren()
Returns true if this Inventory contains children.
|
Inventory |
intersect(Inventory inventory)
Intersects the slots of both inventories.
|
<T extends Inventory> |
next()
Return the next sibling inventory, allows traversing the inventory
hierarchy without using an iterator.
|
InventoryTransactionResult |
offer(ItemStack stack)
Try to put an ItemStack into this Inventory.
|
Inventory |
parent()
|
Optional<ItemStack> |
peek()
Gets without removing the first available stack from this Inventory.
|
Optional<ItemStack> |
peek(int limit)
Uses the same semantics as
poll(int) but does not remove the
items from the inventory. |
Optional<ItemStack> |
poll()
Gets and remove the first available stack from this Inventory.
|
Optional<ItemStack> |
poll(int limit)
Get and remove up to
limit items of the type in the first
available stack in this Inventory from all stacks in this Inventory. |
default <T extends Inventory> |
query(Class<?>... types)
Deprecated.
use
query(QueryOperation...) instead |
default <T extends Inventory> |
query(InventoryProperty<?,?>... props)
Deprecated.
use
query(QueryOperation...) instead |
default <T extends Inventory> |
query(ItemStack... types)
Deprecated.
use
query(QueryOperation...) instead |
default <T extends Inventory> |
query(ItemType... types)
Deprecated.
use
query(QueryOperation...) instead |
default <T extends Inventory> |
query(Object... args)
Deprecated.
use
instead |
<T extends Inventory> |
query(QueryOperation<?>... operations)
Query this inventory for inventories matching any of the supplied
queries.
|
default <T extends Inventory> |
query(Translation... names)
Deprecated.
use
instead |
default <T extends Inventory> |
queryAny(ItemStack... types)
Deprecated.
use
query(QueryOperation...) instead |
Inventory |
root()
|
InventoryTransactionResult |
set(ItemStack stack)
Forcibly put the supplied stack into this inventory.
|
void |
setMaxStackSize(int size)
Sets the maximum stack size of any stack in this ItemList.
|
int |
size()
The number of non-empty slots in the Inventory.
|
<T extends Inventory> |
slots()
Returns an iterable view of all
Slot s (leaf nodes) in this
Inventory. |
int |
totalItems()
Returns the number total number of individual items in this
inventory.
|
default Inventory |
transform(InventoryTransformation transformation)
Transforms this inventory using the given transformation.
|
Inventory |
union(Inventory inventory)
Constructs a union of the slots in both inventories.
|
forEach, iterator, spliterator
static Inventory.Builder builder()
Inventory.Builder
to build an Inventory
.Inventory parent()
Inventory root()
Inventory
of this Inventory
.
This is equivalent to calling parent()
until it returns itself.<T extends Inventory> Iterable<T> slots()
Slot
s (leaf nodes) in this
Inventory.T
- expected inventory type, specified as generic to allow easy
pseudo-duck-typing<T extends Inventory> T first()
Inventory::iterator().next()
but more convenient when we are
expecting a result set with only a single entry. Also use type specifier
to allow easy pseudo-duck-typing. If no children, then returns
this
.T
- expected inventory type, specified as generic to allow easy
pseudo-duck-typingthis
<T extends Inventory> T next()
EmptyInventory
.T
- expected inventory type, specified as generic to allow easy
pseudo-duck-typingEmptyInventory
if
there are no further siblingsOptional<ItemStack> poll()
'Available' has a different meaning for different inventory types. In
a single-slot inventory this has a fixed implication. However larger and
more complex inventories are at liberty to implement whatever logic they
wish to back this method. If an inventory cannot provide a meaningful
implementation of this method then it should return
Optional.empty()
instead.
For consumers, this means that just because an inventory doesn't return anything here, this does not imply that the inventory is empty, just that a more specific query is required to obtain items from it.
Optional.empty()
if
unavailable or unsupportedOptional<ItemStack> poll(int limit)
Get and remove up to limit
items of the type in the first
available stack in this Inventory from all stacks in this Inventory. If
no stack is available then Optional.empty()
is returned (as per
the usual behaviour of poll()
, otherwise a new ItemStack
is returned containing the removed items, the contents of the stack in
the inventory are reduced by the number of items consumed. Note that this
method attempts to consume items into the output up to
limit
, which may consume items from an arbitrary number
of internal slots.
For example, assume an inventory containing 4 slots contains stacks as follows:
[Stone x10] [Dirt x3] [Arrows x9] [Stone x32]
Calling poll(16)
on this inventory will consume Stone
from the Inventory (because the first stack contains stone), and
will then consume the remaining 6 items from the 4th slot.
It is intended that this method is used in conjunction with a query which returns a set of slots containing a specific item type:
Optional<ItemStack> q = inv.query(ItemTypes.DIRT).poll(1);
Optional<ItemStack> peek()
poll()
.Optional.empty()
if
unavailable or unsupportedInventoryTransactionResult offer(ItemStack stack)
Queue
, this method returns true if the Inventory
accepted the stack and false if not, the size of the supplied stack is
reduced by the number of items successfully consumed by the Inventory.
Unlike set(org.spongepowered.api.item.inventory.ItemStack)
, this method's general contract does not permit
items in the Inventory to be replaced. However trying to insert items
that an Inventory cannot accept is not an error condition, the size of
the supplied stack will simply not be reduced if no items are consumed by
the Inventory.
stack
- A stack of items to attempt to insert into the Inventory,
note that upon successful insertion the supplied ItemStack itself
will be mutated and returned with size reduced by the number of
items successfully consumed by the Inventoryboolean canFit(ItemStack stack)
If this returns true
offer(ItemStack)
should always succeed.
stack
- The stack of items to check if it can fit in this inventory.InventoryTransactionResult set(ItemStack stack)
The general contract of this method is to prioritise insertion of the supplied items over items already in the Inventory. However the Inventory may still reject the supplied items if they are of an unsupported type for the target (for example trying to insert non-fuel items into a fuel slot) or if the number of items is larger than the total capacity of the inventory and not all items from the supplied stack can be consumed.
For Slot
s, the supplied stack is generally consumed and the
existing contents ejected (at the discretion of the target Inventory).
For multi-slot inventories the insertion order is up to the target
inventory to decide, and does not have to match the traversal order of
the leaf nodes as supplied by slots()
, although this is
generally recommended. Inventories should document their specific
insertion logic where the insertion order differs from the traversal
order.
Consumers should inspect the returned
InventoryTransactionResult
and act accordingly. Ejected items
should generally be "thrown" into the world or deposited into another
Inventory (depending on the operation in question. The supplied stack is
not adjusted, any rejected items are returned in the operation result
struct.
stack
- the stack to insert into the Inventory, will be mutated by
the number of items successfully consumedvoid clear()
int size()
Slot
s and always 0 for EmptyInventory
s.int totalItems()
This equivalent to counting up the stack sizes of all slots.
int capacity()
Slot
s and always 0 for EmptyInventory
s.boolean hasChildren()
peek()
, poll()
, offer(org.spongepowered.api.item.inventory.ItemStack)
and
set(org.spongepowered.api.item.inventory.ItemStack)
semantics even if it has no internal storage of its own.boolean contains(ItemStack stack)
!inv.query(stack).hasChildren();
To check if an
inventory contains any amount use containsAny(ItemStack)
.stack
- The stack to check forboolean contains(ItemType type)
!inv.query(stack)
.hasChildren();
type
- The type to search forboolean containsAny(ItemStack stack)
contains(ItemStack)
.stack
- The stack to check forint getMaxStackSize()
void setMaxStackSize(int size)
size
- The new maximum stack size<T extends InventoryProperty<?,?>> Collection<T> getProperties(Inventory child, Class<T> property)
T
- expected type of inventory property, generic to enable easy
pseudo-duck-typingchild
- the child inventory to inspectproperty
- the type of property to query for<T extends InventoryProperty<?,?>> Collection<T> getProperties(Class<T> property)
inv.getParent().getProperty(inv, property);
but for
top-level inventories may include properties defined on the inventory
directly.T
- expected type of inventory property, generic to enable easy
pseudo-duck-typingproperty
- the type of property to query for<T extends InventoryProperty<?,?>> Optional<T> getProperty(Inventory child, Class<T> property, Object key)
T
- expected type of inventory property, generic to enable easy
pseudo-duck-typingchild
- the child inventory to inspectproperty
- the type of property to query forkey
- Property key to search for<T extends InventoryProperty<?,?>> Optional<T> getProperty(Class<T> property, Object key)
inv.getParent().getProperty(inv, property, key);
but for
top-level inventories may include properties defined on the inventory
directly.T
- expected type of inventory property, generic to enable easy
pseudo-duck-typingproperty
- the type of property to query forkey
- Property key to search for<T extends InventoryProperty<?,?>> Optional<T> getInventoryProperty(Inventory child, Class<T> property)
T
- expected type of inventory property, generic to enable easy
pseudo-duck-typingchild
- the child inventory to inspectproperty
- the type of property to query for<T extends InventoryProperty<?,?>> Optional<T> getInventoryProperty(Class<T> property)
inv.getParent().getProperty(inv, property);
but for
top-level inventories may include properties defined on the inventory
directly.T
- expected type of inventory property, generic to enable easy
pseudo-duck-typingproperty
- the type of property to query for@Deprecated default <T extends Inventory> T query(Class<?>... types)
query(QueryOperation...)
insteadinstanceof
check against each child
inventory. Logical OR
is applied between operands.T
- expected inventory type, specified as generic to allow easy
pseudo-duck-typingtypes
- inventory types (interfaces or classes) to query for@Deprecated default <T extends Inventory> T query(ItemType... types)
query(QueryOperation...)
insteadSlot
leaf nodes in the
inventory and will always return a collection containing only
Slot
instances. Logical OR
is applied between
operands.T
- expected inventory type, specified as generic to allow easy
pseudo-duck-typingtypes
- item types to query for@Deprecated default <T extends Inventory> T query(ItemStack... types)
query(QueryOperation...)
insteadSlot
leaf nodes in the inventory and will always return a collection
containing only Slot
instances.
To query for stacks of any size use queryAny(ItemStack...)
.T
- expected inventory type, specified as generic to allow easy
pseudo-duck-typingtypes
- items to query for, stack sizes must match the supplied
stack exactly@Deprecated default <T extends Inventory> T query(InventoryProperty<?,?>... props)
query(QueryOperation...)
insteadequals
method of each property is called on
each child inventory which has the supplied property. Logical
OR
is applied between operands. This method is effectively
the same as calling query(java.lang.Class<?>...)
with an
Property.Operator
of
Property.Operator.EQUAL
.T
- expected inventory type, specified as generic to allow easy
pseudo-duck-typingprops
- inventory properties to query for@Deprecated default <T extends Inventory> T query(Translation... names)
instead
OR
is applied between operands.T
- expected inventory type, specified as generic to allow easy
pseudo-duck-typingnames
- the names of the inventories to search for@Deprecated default <T extends Inventory> T query(Object... args)
instead
Query this inventory by dynamically inspecting each operand. Each operand in turn is checked for a match against the other query methods, and if a matching method is found the query is performed using the operand. This is repeated until all operands are consumed and allows a union of multiple query types to be aggregated into a single view.
For operands with no matching type, the behaviour is determined by the individual inventory. A naive match may be obtained by calling .equals() against the child inventory passing the unknown operand as an argument.
T
- expected inventory type, specified as generic to allow easy
pseudo-duck-typingargs
- search parameters@Deprecated default <T extends Inventory> T queryAny(ItemStack... types)
query(QueryOperation...)
insteadSlot
leaf nodes in the inventory and will always
return a collection containing only Slot
instances. Logical
OR
is applied between operands.
This ignores stack sizes. To query for stacks of a specific size use
query(ItemStack...)
.T
- expected inventory type, specified as generic to allow easy
pseudo-duck-typingtypes
- items to query for, the size of the stacks is always ignored<T extends Inventory> T query(QueryOperation<?>... operations)
OR
is applied between operands.T
- expected inventory type, specified as generic to allow easy
pseudo-duck-typingoperations
- queries to check againstPluginContainer getPlugin()
PluginContainer
who built this inventory.InventoryArchetype getArchetype()
InventoryArchetype
based on this Inventory
.Inventory intersect(Inventory inventory)
inventory
- the other inventoryInventory union(Inventory inventory)
The resulting inventory will contain all slots from both inventories.
The slots of this inventory are ordered before the slots of the given inventory.
If the same slot is contained in both inventories the duplicate in the second one is removed.
inventory
- the other inventoryboolean containsInventory(Inventory inventory)
intersect(Inventory)
instead.
You can use this if you want to check if a single Slot is contained in an inventory or an entire row is contained in a Grid.
inventory
- the other inventorydefault Inventory transform(InventoryTransformation transformation)
transformation
- The transformation