Struct ItemStack 

pub struct ItemStack {
    pub item: ItemRef,
    pub count: i32,
    patch: DataComponentPatch,
}

A stack of items with a count and component modifications.

Fields

item: ItemRef

The item type. AIR represents an empty stack.

count: i32

The number of items in this stack.

patch: DataComponentPatch

Modifications to the prototype components.

Implementations

impl ItemStack

pub fn empty() -> Self

Creates an empty item stack (using AIR).

pub fn new(item: ItemRef) -> Self

Creates a new item stack with count 1.

pub fn with_count(item: ItemRef, count: i32) -> Self

Creates a new item stack with the specified count.

pub fn with_count_and_patch( item: ItemRef, count: i32, patch: DataComponentPatch, ) -> Self

Creates a new item stack with the specified count and component patch.

const fn prototype(&self) -> &'static DataComponentMap

pub fn is_empty(&self) -> bool

pub fn item(&self) -> ItemRef

pub fn count(&self) -> i32

pub const fn components_patch(&self) -> &DataComponentPatch

pub const fn set_count(&mut self, count: i32)

pub const fn grow(&mut self, amount: i32)

Increases the count by the given amount.

pub const fn shrink(&mut self, amount: i32)

Decreases the count by the given amount.

pub const fn shrink_one(&mut self)

Decreases the count by one.

pub const fn consume(&mut self, amount: i32, has_infinite_materials: bool)

Decreases the count by the given amount, unless the user has infinite materials.

See: Player::has_infinite_materials

pub const fn consume_one(&mut self, has_infinite_materials: bool)

Consumes a single item from this stack.

pub fn consume_and_return( &mut self, amount: i32, has_infinite_materials: bool, ) -> Self

Splits off the given amount and consumes it from this stack.

pub fn split(&mut self, amount: i32) -> Self

Splits off the specified amount from this stack and returns it as a new stack.

If the amount is greater than or equal to the current count, this stack becomes empty and the entire contents are returned.

pub fn copy_with_count(&self, count: i32) -> Self

Copies the identity (item type and patch) from another stack.

Used when splitting stacks to preserve components.

pub fn is_stackable(&self) -> bool

Returns true if this item can stack (max stack size > 1 and not damaged). Damaged items cannot stack.

pub fn is_damageable_item(&self) -> bool

Returns true if this item can take damage.

pub fn is_damaged(&self) -> bool

Returns true if this item has taken damage.

pub fn get_damage_value(&self) -> i32

Gets the current damage value of this item.

pub fn set_damage_value(&mut self, value: i32)

Sets the damage value of this item.

pub fn get_max_damage(&self) -> i32

Gets the maximum damage this item can take before breaking.

pub fn is_broken(&self) -> bool

Returns true if the item is broken (damage >= max damage).

pub fn next_damage_will_break(&self) -> bool

Returns vanilla ItemStack.nextDamageWillBreak().

pub fn hurt_and_break( &mut self, amount: i32, has_infinite_materials: bool, ) -> bool

Damages the item and breaks it if durability reaches zero.

Returns true if the item broke and should be removed/replaced.

pub fn hurt_and_break_with_random( &mut self, amount: i32, has_infinite_materials: bool, random: &mut impl Random, ) -> bool

Damages the item using the supplied random source for data-driven minecraft:item_damage enchantment effects.

Returns true if the item broke and should be removed/replaced.

fn process_durability_change( &self, amount: i32, random: &mut impl Random, ) -> i32

pub fn has<T: 'static>(&self, component: DataComponentType<T>) -> bool

Returns true if this item has the specified component (by type).

pub fn has_component(&self, key: &Identifier) -> bool

Returns true if this item has the specified component (by key).

pub fn is_same_item(a: &Self, b: &Self) -> bool

pub fn is_same_item_same_components(a: &Self, b: &Self) -> bool

Checks if two stacks have the same item and components.

pub fn matches(a: &Self, b: &Self) -> bool

pub fn is(&self, item: ItemRef) -> bool

pub fn max_stack_size(&self) -> i32

pub fn validate_strict(&self) -> Result<()>

Validates the complete stack constraints enforced by Vanilla’s ItemStack.validateStrict.

pub fn get_equippable(&self) -> Option<&Equippable>

Returns the equippable component if this item has one.

pub fn get_attribute_modifiers(&self) -> Option<&ItemAttributeModifiers>

Returns the item attribute modifiers component.

pub fn get_equippable_slot(&self) -> Option<EquipmentSlot>

Returns the equipment slot this item can be equipped to, if any.

pub fn is_equippable_in_slot(&self, slot: EquipmentSlot) -> bool

Returns true if this item can be equipped in the given slot.

pub fn get_effective_value_raw( &self, key: &Identifier, ) -> Option<&ComponentData>

Gets the raw component data by key.

pub fn get<T: Component + DowncastType>( &self, component: DataComponentType<T>, ) -> Option<&T>

Gets the effective value of a component, considering the patch and prototype. Returns None if the component is not present or has been removed.

pub fn get_or_default<T: Component + DowncastType + Clone>( &self, component: DataComponentType<T>, default: T, ) -> T

Gets the effective value of a component, or returns the default value if not present.

pub fn set<T: Component + DowncastType>( &mut self, component: DataComponentType<T>, value: T, )

Sets a component value in this item’s patch, overriding the prototype.

pub fn remove<T: 'static>(&mut self, component: DataComponentType<T>)

Removes a component from this item (marks it as removed in the patch). This will hide the component even if it exists in the prototype.

pub fn clear<T: 'static>(&mut self, component: DataComponentType<T>)

Clears any patch entry for this component (neither set nor removed). The prototype value will be visible again.

pub const fn patch(&self) -> &DataComponentPatch

Returns a reference to the component patch.

pub fn get_tool(&self) -> Option<&Tool>

Gets the Tool component if present.

pub fn get_weapon(&self) -> Option<&Weapon>

Gets the Weapon component if present.

pub fn get_attack_range(&self) -> Option<&AttackRange>

Gets the AttackRange component if present.

pub fn minimum_attack_charge(&self) -> f32

Returns vanilla DataComponents.MINIMUM_ATTACK_CHARGE, defaulting to 0.

pub fn get_damage_type(&self) -> Option<DamageTypeRef>

Gets the vanilla damage type component if present.

pub fn can_be_hurt_by(&self, damage_type: DamageTypeRef) -> bool

Returns vanilla ItemStack.canBeHurtBy for a damage type.

pub fn is_valid_repair_item(&self, repair_item: &Self) -> bool

Returns vanilla ItemStack.isValidRepairItem.

pub fn is_piercing_weapon(&self) -> bool

Returns whether this item has the vanilla piercing weapon component.

pub fn get_piercing_weapon(&self) -> Option<&PiercingWeapon>

Gets the PiercingWeapon component if present.

pub fn get_destroy_speed(&self, block_state_id: BlockStateId) -> f32

Returns the mining speed for the given block state ID. If no Tool component is present, returns 1.0 (hand speed).

pub fn is_correct_tool_for_drops(&self, block_state_id: BlockStateId) -> bool

Returns true if this tool is correct for getting drops from the block.

pub fn get_tool_damage_per_block(&self) -> i32

Returns the damage per block for this tool (how much durability is consumed per block mined). Returns 0 if no Tool component is present.

pub fn can_destroy_blocks_in_creative(&self) -> bool

Returns true if this tool can destroy blocks in creative mode. Returns true if no Tool component is present (default behavior).

pub fn get_enchantment_level(&self, enchantment: &Identifier) -> i32

pub fn get_enchantments(&self) -> Option<&ItemEnchantments>

pub fn get_enchantments_for_crafting(&self) -> Option<&ItemEnchantments>

Vanilla EnchantmentHelper.getEnchantmentsForCrafting: enchanted books expose STORED_ENCHANTMENTS to crafting operations, while every other item exposes ENCHANTMENTS.

fn enchantment_component(&self) -> DataComponentType<ItemEnchantments>

Vanilla EnchantmentHelper.getComponentType.

pub fn is_enchantable(&self) -> bool

Mirrors Vanilla’s component-based ItemStack.isEnchantable check.

pub fn is_enchanted(&self) -> bool

Checks if ItemStack has an enchantment

pub fn has_enchantment_effect( &self, component: EnchantmentEffectComponent, ) -> bool

pub fn apply_unconditional_enchantment_value_effects( &self, component: EnchantmentEffectComponent, input: f32, ) -> f32

pub const fn set_damage_fraction(&mut self, _fraction: f32, _add: bool)

Sets the damage/durability as a fraction (0.0 = broken, 1.0 = full). If add is true, adds to current damage instead of setting.

pub const fn enchant_randomly<R: Rng>( &mut self, _options: &EnchantmentOptions, _rng: &mut R, )

Enchants this item randomly with enchantments from the given options.

pub const fn enchant_with_levels<R: Rng>( &mut self, _level: i32, _options: &EnchantmentOptions, _rng: &mut R, )

Enchants this item as if using an enchanting table at the given level.

pub const fn copy_components<R: Rng>( &mut self, _source: CopySource, _include: &[Identifier], _ctx: &LootContext<'_, R>, )

Copies components from a source (block entity, attacker, etc.) to this item.

pub const fn copy_block_state<R: Rng>( &mut self, _block: &Identifier, _properties: &[&str], _ctx: &LootContext<'_, R>, )

Copies block state properties to this item (for blocks like note_block).

pub const fn set_components_from_json(&mut self, _components: &str)

Sets components from a JSON string representation.

pub fn set_custom_data(&mut self, value: &CustomData)

Merges custom NBT data into this item’s custom_data component.

pub fn apply_furnace_smelt(&mut self, use_input_count: bool)

Applies furnace smelting to convert this item (e.g., raw iron -> iron ingot).

pub const fn create_exploration_map( &mut self, _destination: &Identifier, _decoration: &Identifier, _zoom: i32, _skip_existing_chunks: bool, )

Creates an exploration map pointing to a structure.

pub const fn set_name(&mut self, _name: &str, _target: NameTarget)

Sets the custom name or item name of this item.

pub fn set_ominous_bottle_amplifier(&mut self, amplifier: i32)

Sets the ominous bottle amplifier component.

pub const fn set_potion(&mut self, _id: &Identifier)

Sets the potion type for this item.

pub const fn set_stew_effects<R: Rng>( &mut self, _effects: &[StewEffect], _rng: &mut R, )

Sets the suspicious stew effects for this item.

pub fn set_enchantments( &mut self, enchantments: &[(Identifier, u32)], add: bool, )

pub fn upgrade_enchantment(&mut self, enchantment: Identifier, level: u32)

Vanilla ItemStack.enchant → Mutable.upgrade: keeps the higher of existing vs new level.

pub fn set_item(&mut self, new_item: &Identifier)

Changes the item type entirely.

pub const fn copy_name<R: Rng>( &mut self, _source: CopySource, _ctx: &LootContext<'_, R>, )

Copies the name from a source entity/block to this item.

pub const fn set_lore(&mut self, _lore: &[&str], _mode: ListOperation)

Sets lore lines on this item.

pub const fn set_contents<R: Rng>( &mut self, _entries: &[LootEntry], _component_type: &Identifier, _ctx: &mut LootContext<'_, R>, )

Sets container inventory contents.

pub const fn modify_contents<R: Rng>( &mut self, _modifier: &[ConditionalLootFunction], _component_type: &Identifier, _ctx: &mut LootContext<'_, R>, )

Modifies existing container contents.

pub const fn set_loot_table( &mut self, _loot_table: &Identifier, _seed: Option<i64>, )

Sets the container’s loot table reference.

pub const fn set_attributes<R: Rng>( &mut self, _modifiers: &[AttributeModifier], _replace: bool, _rng: &mut R, )

Sets attribute modifiers on this item.

pub const fn fill_player_head<R: Rng>( &mut self, _entity: LootContextEntity, _ctx: &LootContext<'_, R>, )

Fills a player head with texture from an entity.

pub const fn copy_custom_data<R: Rng>( &mut self, _source: CopySource, _operations: &[CopyDataOperation], _ctx: &LootContext<'_, R>, )

Copies custom NBT data from a source.

pub const fn set_banner_pattern( &mut self, _patterns: &[BannerPattern], _append: bool, )

Sets banner pattern layers.

pub const fn set_fireworks( &mut self, _explosions: Option<&[FireworkExplosion]>, _flight_duration: Option<i32>, )

Sets firework rocket properties.

pub const fn set_firework_explosion(&mut self, _explosion: &FireworkExplosion)

Sets firework star explosion properties.

pub const fn set_book_cover( &mut self, _title: Option<&str>, _author: Option<&str>, _generation: Option<i32>, )

Sets book cover (title/author for written books).

pub const fn set_written_book_pages( &mut self, _pages: &[&str], _mode: ListOperation, )

Sets written book page contents.

pub const fn set_writable_book_pages( &mut self, _pages: &[&str], _mode: ListOperation, )

Sets writable book page contents.

pub fn toggle_tooltips(&mut self, toggles: &[(Identifier, bool)])

Runs vanilla ToggleTooltips: each boolean says whether the component is shown.

pub fn components_equal(&self, other: &Self) -> bool

pub fn custom_name(&self) -> Option<Cow<'_, TextComponent>>

Vanilla ItemStack.getCustomName: an explicit custom name, or a nonblank written-book title.

pub fn custom_or_component_name(&self) -> Cow<'_, TextComponent>

Returns the custom name if set, otherwise the effective ITEM_NAME component.

This does not apply item-class name overrides such as potion contents; callers with access to item behaviors should use their behavior-aware hover-name API.

impl ItemStack

pub fn read_untrusted(data: &mut Cursor<&[u8]>) -> Result<Self>

Reads an item stack using the delimited (untrusted) component format.

Vanilla uses this for serverbound packets where component data is length-prefixed (e.g., ServerboundSetCreativeModeSlotPacket).

impl ItemStack

pub fn validate_persistent_encoding(&self) -> Result<()>

Checks that this stack can be encoded by Vanilla’s persistent ItemStack.CODEC before untrusted network data enters server state.

This is an ingress check rather than a type invariant: programmatic component mutation can still create values whose save codec reports and omits invalid fields.

pub fn to_nbt_tag_ref(&self) -> NbtTag

Converts this item stack to an NBT tag for persistent storage without consuming it.

impl ItemStack

pub fn from_borrowed_compound( compound: &NbtCompoundView<'_, '_>, ) -> Option<Self>

Parses an ItemStack from a borrowed NbtCompoundView.

This is useful for loading items from disk where we have borrowed NBT data and want to avoid the overhead of converting to an owned tag first.

Trait Implementations

impl Clone for ItemStack

fn clone(&self) -> ItemStack

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ItemStack

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ItemStack

fn default() -> Self

Returns the “default value” for a type.

impl Display for ItemStack

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<&'static Item> for ItemStack

fn from(item: ItemRef) -> Self

Converts to this type from the input type.

impl From<&'static LazyLock<Item>> for ItemStack

fn from(item: &'static LazyLock<Item>) -> Self

Converts to this type from the input type.

impl From<&ItemStack> for ItemStack

fn from(stack: &Self) -> Self

Converts to this type from the input type.

impl FromNbtTag for ItemStack

fn from_nbt_tag(tag: BorrowedNbtTag<'_, '_>) -> Option<Self>

Parses an item stack from an NBT tag.

Accepts the vanilla format:

{
    id: "minecraft:stone",
    count: 64,
    components: { ... }
}

fn from_optional_nbt_tag( tag: Option<NbtTag<'_, '_>>, ) -> Result<Option<Self>, DeserializeError>

impl PartialEq for ItemStack

fn eq(&self, other: &ItemStack) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl ReadFrom for ItemStack

fn read(data: &mut Cursor<&[u8]>) -> Result<Self>

Reads data from a cursor.

impl StructuralPartialEq for ItemStack

impl ToNbtTag for ItemStack

fn to_nbt_tag(self) -> NbtTag

Converts this item stack to an NBT tag for persistent storage.

Format (matching vanilla Minecraft):

{
    id: "minecraft:stone",
    count: 64,
    components: { ... }  // Only present if patch is non-empty
}

fn to_optional_nbt_tag(self) -> Option<NbtTag>

impl WriteTo for ItemStack

fn write(&self, writer: &mut impl Write) -> Result<()>

Writes data to a writer.