Struct ItemStack
#[non_exhaustive]pub struct ItemStack { /* private fields */ }Expand description
A nonempty, owned item value. Maxima are checked when the game accepts a write,
not by this record: item definitions and effective component overrides belong to the game.
The component patch is shared copy-on-write: Clone counts a reference instead of
copying it, the first write through a shared stack copies the patch once, and equality
of two stacks that still share it is a pointer comparison. An absent patch allocates nothing.
An untouched mutable stack hook argument retains its engine value without write validation, even when the engine value exceeds effective maxima. Equality with the snapshot passed to the listener determines whether it changed; a changed argument is validated in full before committing any hook outputs. A refused hook output retains its captured engine value. The clicked-slot bridge also stages the slot, cursor and cancellation flags together. Independent host effects, including storage writes, commands and messages, are not undone by output validation.
Implementations§
§impl ItemStack
impl ItemStack
pub fn new(item: ItemKey, count: u32) -> Option<ItemStack>
pub fn new(item: ItemKey, count: u32) -> Option<ItemStack>
Construct a nonempty stack. Registry maxima are validated by the game on writes.
pub fn set_count(&mut self, count: u32) -> Result<(), StackError>
pub fn set_count(&mut self, count: u32) -> Result<(), StackError>
Change the count without consulting the game. A refusal leaves the value unchanged.
pub fn damage(&self) -> u32
pub fn damage(&self) -> u32
Stored damage, or zero when no numeric damage override is present.
A plain stack inherits its item’s default. Some(0) is an explicit present zero;
Self::clear_damage records removal of the default component instead.
pub fn damage_component(&self) -> Option<u32>
pub fn damage_component(&self) -> Option<u32>
The numeric damage override: None inherits the prototype unless the patch contains an explicit removal; Some(0) is a present zero-damage component.
pub fn set_damage(&mut self, damage: u32)
pub fn set_damage(&mut self, damage: u32)
Set damage. The game checks the effective maximum when accepting this value.
pub fn clear_damage(&mut self)
pub fn clear_damage(&mut self)
Remove the effective damage component, including an inherited default. The patch stores a real NBT removal, never a second numeric damage value.
pub fn is_damaged(&self) -> bool
pub fn is_damaged(&self) -> bool
Whether a nonzero numeric damage override is stored on the stack.
pub fn grow(&mut self, count: u32) -> Result<(), StackError>
pub fn grow(&mut self, count: u32) -> Result<(), StackError>
Add items. Overflow leaves the stack unchanged; registry maxima are checked on writes.
pub fn shrink(self, count: u32) -> Option<ItemStack>
pub fn shrink(self, count: u32) -> Option<ItemStack>
Remove items, consuming the value so removing everything needs no empty sentinel.
pub fn split(self, count: u32) -> StackSplit
pub fn split(self, count: u32) -> StackSplit
Take up to count items. A full split moves the patch without cloning it.
pub fn same_item(&self, other: &ItemStack) -> bool
pub fn same_item(&self, other: &ItemStack) -> bool
Compare item identities, independent of count and components.
pub fn same_components(&self, other: &ItemStack) -> bool
pub fn same_components(&self, other: &ItemStack) -> bool
Compare component patches and damage, independent of count and item identity.
pub fn is_stackable_with(&self, other: &ItemStack) -> bool
pub fn is_stackable_with(&self, other: &ItemStack) -> bool
Whether these values have the same item and component patch. Capacity is a registry-dependent write-boundary check, not a promise of this predicate.
pub fn get<C>(&self, component: &C) -> Option<<C as Component>::Value>where
C: Component,
pub fn get<C>(&self, component: &C) -> Option<<C as Component>::Value>where
C: Component,
Read a component with its typed descriptor.
pub fn set<C>(
&mut self,
component: &C,
value: <C as Component>::Value,
) -> Result<(), StackError>where
C: Component,
pub fn set<C>(
&mut self,
component: &C,
value: <C as Component>::Value,
) -> Result<(), StackError>where
C: Component,
Replace a component value. Only stacks with a patch allocate component storage.
pub fn remove<C>(&mut self, component: &C)where
C: Component,
pub fn remove<C>(&mut self, component: &C)where
C: Component,
Remove an override, releasing the patch allocation when its last entry is removed.
pub fn components(&self) -> Option<&Components>
pub fn components(&self) -> Option<&Components>
The component patch, if this stack has overrides.
pub fn set_components(
&mut self,
patch: BTreeMap<JavaString, Tag>,
) -> Result<(), StackError>
pub fn set_components( &mut self, patch: BTreeMap<JavaString, Tag>, ) -> Result<(), StackError>
Replace the component patch at an NBT conversion boundary. Damage is normalized into the scalar field. Malformed or conflicting values refuse the entire replacement and leave the stack unchanged.
pub fn from_nbt(
host: &dyn Host,
value: &BTreeMap<JavaString, Tag>,
) -> Option<ItemStack>
pub fn from_nbt( host: &dyn Host, value: &BTreeMap<JavaString, Tag>, ) -> Option<ItemStack>
Decode the item NBT escape using this host’s load-resolved item ids. Unknown ids, zero counts and malformed/conflicting damage return None. Effective maxima remain the game’s write-boundary responsibility.
pub fn to_nbt(&self, host: &dyn Host) -> Option<BTreeMap<JavaString, Tag>>
pub fn to_nbt(&self, host: &dyn Host) -> Option<BTreeMap<JavaString, Tag>>
Encode the item NBT escape using this host’s canonical id, never a process-local key. Returns None when id metadata is unavailable. Only components present on the stack are written; effective defaults and maxima belong to the items host area.