ItemStack

ItemStack

Package: com.hypixel.hytale.server.core.inventory

public class ItemStack implements NetworkSerializable<ItemWithAllMetadata>

Represents a stack of items in the Hytale inventory system. ItemStack follows an immutable-style pattern: all with* methods return a new ItemStack instance rather than mutating the current one. This makes ItemStack safe to pass around without defensive copying, though the class itself is not strictly immutable (fields are protected, and the BuilderCodec mutates fields during deserialization).

Each ItemStack is identified by a string itemId that corresponds to an asset-defined item type. The special item ID "Empty" is reserved for the singleton EMPTY instance and cannot be used to construct normal stacks.

Static Fields

EMPTY_ARRAY

@Nonnull
public static final ItemStack[] EMPTY_ARRAY = new ItemStack[0]

Shared empty array constant to avoid unnecessary allocations.

CODEC

@Nonnull
public static final BuilderCodec<ItemStack> CODEC

Serialization codec for ItemStack. Encodes and decodes the following keyed fields:

Key	Codec	Validation
"Id"	Codec.STRING	Non-null; must pass Item.VALIDATOR_CACHE
"Quantity"	Codec.INTEGER	Greater than 0
"Durability"	Codec.DOUBLE	Greater than or equal to 0.0
"MaxDurability"	Codec.DOUBLE	Greater than or equal to 0.0
"Metadata"	Codec.BSON_DOCUMENT	None
"OverrideDroppedItemAnimation"	Codec.BOOLEAN	None

The codec uses BuilderCodec.builder() with a no-arg constructor, so deserialization creates an empty ItemStack and sets fields directly via lambda setters.

EMPTY

@Nonnull
public static final ItemStack EMPTY

Singleton empty item stack. Has itemId = "Empty". Use isEmpty() to check whether an ItemStack is the empty sentinel.

Constructors

Primary Constructor

public ItemStack(@Nonnull String itemId, int quantity, @Nullable BsonDocument metadata)

Creates an item stack with the given item ID, quantity, and optional metadata. Durability is initialized from the item’s asset definition (Item.getMaxDurability()).

Throws:

• IllegalArgumentException if quantity <= 0
• IllegalArgumentException if itemId is null
• IllegalArgumentException if itemId equals "Empty"

Full Constructor

public ItemStack(@Nonnull String itemId, int quantity, double durability, double maxDurability, @Nullable BsonDocument metadata)

Creates an item stack with explicit durability values. Delegates to the primary constructor, then overrides durability and maxDurability.

Convenience Constructors

public ItemStack(@Nonnull String itemId)

Creates a stack of 1 with no metadata. Equivalent to new ItemStack(itemId, 1, null).

public ItemStack(@Nonnull String itemId, int quantity)

Creates a stack with the given quantity and no metadata. Equivalent to new ItemStack(itemId, quantity, null).

Instance Methods

Identity and State

@Nonnull
public String getItemId()

Returns the string item identifier (e.g., "hytale:wooden_sword").

public int getQuantity()

Returns the number of items in this stack.

public boolean isEmpty()

Returns true if this is the empty sentinel (itemId equals "Empty").

@Nonnull
public Item getItem()

Resolves the Item asset definition for this stack’s itemId. Returns Item.UNKNOWN if the item ID does not match any registered asset.

public boolean isValid()

Returns true if this stack is empty or its item ID resolves to a known asset.

@Nullable
public String getBlockKey()

Returns the block ID associated with this item if it has a block type (e.g., a placeable block item), "Empty" if the stack is empty, or null if the item has no associated block type.

Durability

public boolean isUnbreakable()

Returns true if maxDurability <= 0.0. An unbreakable item cannot be broken through durability loss.

public boolean isBroken()

Returns true if the item is breakable and its durability has reached 0.0. Always returns false for unbreakable items.

public double getMaxDurability()

Returns the maximum durability value for this stack.

public double getDurability()

Returns the current durability value.

Immutable-Style Transformations

All with* methods return a new ItemStack instance. The original is not modified.

@Nonnull
public ItemStack withDurability(double durability)

Returns a new stack with durability clamped to [0.0, maxDurability].

@Nonnull
public ItemStack withMaxDurability(double maxDurability)

Returns a new stack with the given max durability. Current durability is clamped to min(durability, maxDurability).

@Nonnull
public ItemStack withIncreasedDurability(double inc)

Returns a new stack with durability increased by inc. Internally calls withDurability(this.durability + inc), so the result is clamped.

@Nonnull
public ItemStack withRestoredDurability(double maxDurability)

Returns a new stack with both durability and max durability set to the given value. Effectively “fully repairs” the item with a new max.

@Nonnull
public ItemStack withState(@Nonnull String state)

Returns a new stack with the item ID changed to the ID for the given state. For example, a tool item may have different item IDs for different visual states. Throws IllegalArgumentException if the state is not valid for this item.

@Nullable
public ItemStack withQuantity(int quantity)

Returns a new stack with the given quantity. Returns null if quantity == 0 (the stack is consumed). Returns this if the quantity is unchanged.

Metadata

Metadata is stored as a BsonDocument. Individual metadata values can be accessed through KeyedCodec or raw key/codec pairs.

@Nonnull
public ItemStack withMetadata(@Nullable BsonDocument metadata)

Returns a new stack with the given metadata document, replacing any existing metadata.

@Nonnull
public <T> ItemStack withMetadata(@Nonnull KeyedCodec<T> keyedCodec, @Nullable T data)

Returns a new stack with the metadata value for the given KeyedCodec set (or removed if data is null).

@Nonnull
public <T> ItemStack withMetadata(@Nonnull String key, @Nonnull Codec<T> codec, @Nullable T data)

Returns a new stack with the metadata value at the given key set (or removed if data is null or encodes to an empty/null BSON value). If removing the last key results in an empty document, metadata is set to null.

@Nullable
public <T> T getFromMetadataOrNull(@Nonnull KeyedCodec<T> keyedCodec)

Returns the metadata value decoded by the given KeyedCodec, or null if not present.

@Nullable
public <T> T getFromMetadataOrNull(@Nonnull String key, @Nonnull Codec<T> codec)

Returns the metadata value at the given key decoded by the given Codec, or null if not present.

Stack Comparison

public boolean isStackableWith(@Nullable ItemStack itemStack)

Returns true if this stack can be merged with the given stack. Two stacks are stackable when they have the same item ID, same durability, same max durability, and equal metadata. Quantity is not compared — only identity and state matter.

public boolean isEquivalentType(@Nullable ItemStack itemStack)

Returns true if this stack is the same “type” as the given stack. Like isStackableWith, but ignores durability values. Compares item ID and metadata only.

Network Serialization

public ItemWithAllMetadata toPacket()

Converts this stack to an ItemWithAllMetadata protocol packet for network transmission. The result is cached — repeated calls return the same packet instance. The cache is invalidated implicitly because with* methods create new ItemStack instances rather than mutating this one.

Dropped Item Animation

public boolean getOverrideDroppedItemAnimation()

Returns whether the dropped item animation override flag is set.

public void setOverrideDroppedItemAnimation(boolean b)

Sets the dropped item animation override flag. This is one of the few mutable operations on ItemStack.

Static Methods

public static boolean isEmpty(@Nullable ItemStack itemFrom)

Null-safe emptiness check. Returns true if the stack is null or isEmpty().

public static boolean isStackableWith(@Nullable ItemStack a, ItemStack b)

Null-safe stackability check. Returns true if a == b or a.isStackableWith(b).

public static boolean isEquivalentType(@Nullable ItemStack a, ItemStack b)

Null-safe type equivalence check. Returns true if a == b or a.isEquivalentType(b).

public static boolean isSameItemType(@Nullable ItemStack a, @Nullable ItemStack b)

Returns true if both stacks have the same itemId. Does not compare metadata, durability, or quantity.

@Nullable
public static ItemStack fromPacket(@Nullable ItemQuantity packet)

Creates an ItemStack from an ItemQuantity protocol packet. Returns null if the packet is null or has a quantity of 0 or less.

Inner Classes

Metadata

public static class Metadata

Contains metadata key constants.

Constant	Value
BLOCK_STATE	"BlockState"

Equality and Hashing

ItemStack overrides equals() and hashCode(). Two stacks are equal when they have the same item ID, quantity, durability, max durability, and metadata. This is a stricter comparison than isStackableWith(), which ignores quantity.

Related Types

• Item — asset definition for item types; resolved via getItem()
• BuilderCodec — codec framework used for serialization/deserialization
• KeyedCodec — typed key for accessing individual metadata fields within the BSON document
• Codec — base codec interface for encoding/decoding values
• NetworkSerializable — interface for types that can be serialized to protocol packets
• ItemWithAllMetadata — protocol packet type carrying full item stack data
• ItemQuantity — lightweight protocol packet carrying only item ID and quantity
• MathUtil — utility class providing clamp() used by durability methods
• Store — ECS store; inventory components on entities hold ItemStack instances
• Entity — game entities that carry inventory components containing item stacks