Skip to content

levilamina::item

Items: a value object and not a handle.

On the ABI an item is a string of SNBT throughout. Reading a property means asking a property with that SNBT, and changing one means exchanging that SNBT for a new one through item_transform. This layer copies that shape and hides no pointer in between.

The consequence: an ItemStack has no connection to the item in the world

container.item(0) returns a snapshot. Changing it does not move the one in the container, and writing it back takes an explicit container.set_item(0, &stack). This is the other side of a handle being an identity and not a pointer: with no implicit synchronization in between, there is no I changed it and nothing happened.

ItemStack

Rust
1
2
3
pub struct ItemStack {
    // private fields
}

An SNBT snapshot of one item.

The fields the snapshot itself carries, Name, Count, Damage and the tag compound, are read locally from a parse cached on first use; only properties that need the item registry, such as the stack limit or the attack damage, cross the ABI, where the host parses the SNBT and builds an engine ItemStack for every call.

  • Implements: Clone, PartialEq, Eq, Hash, Debug, Display, From

ItemStack::from_snbt

Rust
1
pub fn from_snbt(snbt: impl Into<String>) -> ItemStack

Uses a string of SNBT directly, without validation, since validating would cross the ABI once and this constructor sits on a hot path. A wrong shape reports an error at the first call that really uses it.

  • Parameters:
    • snbt : impl Into<String>
  • Return type: ItemStack

ItemStack::create

Rust
1
pub fn create(type_name: &str, count: u8) -> ItemStack

Builds one from a type name and a count.

It assembles the minimal shape {Name:"...",Count:Nb} and the engine fills in the rest inside ItemStack::fromTag. A name that does not exist fails at the moment the item is used and not here.

  • Parameters:
    • type_name : &str
    • count : u8
  • Return type: ItemStack

ItemStack::empty

Rust
1
pub fn empty() -> ItemStack

Air. An empty slot in a container reads back as this.

  • Return type: ItemStack

ItemStack::snbt

Rust
1
pub fn snbt(&self) -> &str

The underlying SNBT.

  • Return type: &str

ItemStack::to_nbt

Rust
1
pub fn to_nbt(&self) -> Result<NbtValue>

Parses into an NBT tree, for reading a field the ABI gives no named accessor for.

  • Return type: Result<NbtValue>

ItemStack::num

Rust
1
pub fn num(&self, prop: i32) -> Result<f64>

Reads a PIER_IPROP_* numeric property.

A property number the host does not recognize returns Err and not 0: cannot-be-determined and an answer of 0 must stay apart (contract Β§5.2).

  • Parameters:
    • prop : i32
  • Return type: Result<f64>
  • Slots: item_get_num

ItemStack::count

Rust
1
pub fn count(&self) -> Result<u8>

ItemStack::max_stack_size

Rust
1
pub fn max_stack_size(&self) -> Result<u8>

ItemStack::aux_value

Rust
1
pub fn aux_value(&self) -> Result<i32>

ItemStack::id

Rust
1
pub fn id(&self) -> Result<i32>

ItemStack::damage

Rust
1
pub fn damage(&self) -> Result<i32>

ItemStack::max_damage

Rust
1
pub fn max_damage(&self) -> Result<i32>

ItemStack::attack_damage

Rust
1
pub fn attack_damage(&self) -> Result<i32>

ItemStack::repair_cost

Rust
1
pub fn repair_cost(&self) -> Result<i32>

ItemStack::enchant_value

Rust
1
pub fn enchant_value(&self) -> Result<i32>

ItemStack::use_duration

Rust
1
pub fn use_duration(&self) -> Result<i32>

ItemStack::is_null

Rust
1
pub fn is_null(&self) -> Result<bool>

ItemStack::is_block

Rust
1
pub fn is_block(&self) -> Result<bool>

ItemStack::is_enchanted

Rust
1
pub fn is_enchanted(&self) -> Result<bool>

ItemStack::is_armor

Rust
1
pub fn is_armor(&self) -> Result<bool>

ItemStack::is_damageable

Rust
1
pub fn is_damageable(&self) -> Result<bool>

ItemStack::is_damaged

Rust
1
pub fn is_damaged(&self) -> Result<bool>

ItemStack::is_unbreakable

Rust
1
pub fn is_unbreakable(&self) -> Result<bool>

ItemStack::has_durability

Rust
1
pub fn has_durability(&self) -> Result<bool>

ItemStack::is_potion

Rust
1
pub fn is_potion(&self) -> Result<bool>

ItemStack::is_throwable

Rust
1
pub fn is_throwable(&self) -> Result<bool>

ItemStack::is_fire_resistant

Rust
1
pub fn is_fire_resistant(&self) -> Result<bool>

ItemStack::is_stackable

Rust
1
pub fn is_stackable(&self) -> Result<bool>

ItemStack::is_music_disc

Rust
1
pub fn is_music_disc(&self) -> Result<bool>

ItemStack::is_offhand

Rust
1
pub fn is_offhand(&self) -> Result<bool>

ItemStack::is_glint

Rust
1
pub fn is_glint(&self) -> Result<bool>

ItemStack::is_bundle

Rust
1
pub fn is_bundle(&self) -> Result<bool>

ItemStack::has_user_data

Rust
1
pub fn has_user_data(&self) -> Result<bool>

ItemStack::has_custom_name

Rust
1
pub fn has_custom_name(&self) -> Result<bool>

ItemStack::text

Rust
1
pub fn text(&self, prop: i32) -> Result<String>

Reads a PIER_ISTR_* string property.

  • Parameters:
    • prop : i32
  • Return type: Result<String>
  • Slots: item_get_str

ItemStack::type_name

Rust
1
pub fn type_name(&self) -> Result<String>

ItemStack::name

Rust
1
pub fn name(&self) -> Result<String>

ItemStack::custom_name

Rust
1
pub fn custom_name(&self) -> Result<String>

ItemStack::hover_name

Rust
1
pub fn hover_name(&self) -> Result<String>

ItemStack::raw_name_id

Rust
1
pub fn raw_name_id(&self) -> Result<String>

ItemStack::effect_name

Rust
1
pub fn effect_name(&self) -> Result<String>

ItemStack::lore

Rust
1
pub fn lore(&self) -> Result<Vec<String>>

The custom lore. The host gives an SNBT string list, parsed here into a Vec<String>.

ItemStack::can_destroy

Rust
1
pub fn can_destroy(&self) -> Result<Vec<String>>

ItemStack::can_place_on

Rust
1
pub fn can_place_on(&self) -> Result<Vec<String>>

ItemStack::user_data

Rust
1
pub fn user_data(&self) -> Result<NbtValue>

The custom NBT of the item, the tag section. It goes through a dedicated slot rather than PIER_ISTR_USER_DATA: the content is the same and the dedicated slot saves one property-number dispatch on the host side.

ItemStack::color

Rust
1
pub fn color(&self) -> Result<(i32, i32, i32)>

The color as {r,g,b}. Only a dyeable item has one.

ItemStack::transform

Rust
1
pub fn transform(&mut self, op: i32, sarg: &str, narg: f64) -> Result<()>

Runs one PIER_IOP_* transform and replaces itself with the result.

On failure it stays unchanged: with no new SNBT from the host there is nothing to write back, and writing half a result in is harder to diagnose than doing nothing.

  • Parameters:
    • op : i32
    • sarg : &str
    • narg : f64
  • Return type: Result<()>
  • Slots: item_transform

ItemStack::transformed

Rust
1
pub fn transformed(&self, op: i32, sarg: &str, narg: f64) -> Result<ItemStack>

As above, returning a new item and leaving this one unchanged.

  • Parameters:
    • op : i32
    • sarg : &str
    • narg : f64
  • Return type: Result<ItemStack>

ItemStack::set_custom_name

Rust
1
pub fn set_custom_name(&mut self, name: &str) -> Result<()>
  • Parameters:
    • name : &str
  • Return type: Result<()>
  • Slots: item_transform

ItemStack::reset_name

Rust
1
pub fn reset_name(&mut self) -> Result<()>

ItemStack::set_damage

Rust
1
pub fn set_damage(&mut self, damage: i32) -> Result<()>
  • Parameters:
    • damage : i32
  • Return type: Result<()>
  • Slots: item_transform

ItemStack::set_count

Rust
1
pub fn set_count(&mut self, count: u8) -> Result<()>
  • Parameters:
    • count : u8
  • Return type: Result<()>
  • Slots: item_transform

ItemStack::set_unbreakable

Rust
1
pub fn set_unbreakable(&mut self, on: bool) -> Result<()>

ItemStack::hurt_and_break

Rust
1
pub fn hurt_and_break(&mut self, damage: i32) -> Result<()>
  • Parameters:
    • damage : i32
  • Return type: Result<()>
  • Slots: item_transform

ItemStack::set_repair_cost

Rust
1
pub fn set_repair_cost(&mut self, cost: i32) -> Result<()>
  • Parameters:
    • cost : i32
  • Return type: Result<()>
  • Slots: item_transform

ItemStack::clear_lore

Rust
1
pub fn clear_lore(&mut self) -> Result<()>

ItemStack::remove_enchants

Rust
1
pub fn remove_enchants(&mut self) -> Result<()>

ItemStack::set_lore

Rust
1
pub fn set_lore(&mut self, lines: &[&str]) -> Result<()>
  • Parameters:
    • lines : &[&str]
  • Return type: Result<()>
  • Slots: item_transform

ItemStack::set_can_destroy

Rust
1
pub fn set_can_destroy(&mut self, blocks: &[&str]) -> Result<()>
  • Parameters:
    • blocks : &[&str]
  • Return type: Result<()>
  • Slots: item_transform

ItemStack::set_can_place_on

Rust
1
pub fn set_can_place_on(&mut self, blocks: &[&str]) -> Result<()>
  • Parameters:
    • blocks : &[&str]
  • Return type: Result<()>
  • Slots: item_transform

ItemStack::add_enchant

Rust
1
pub fn add_enchant(&mut self, id: &str, level: i32) -> Result<()>

Adds an enchantment. A level of 0 removes it, as far as the engine is concerned.

  • Parameters:
    • id : &str
    • level : i32
  • Return type: Result<()>
  • Slots: item_transform

ItemStack::enchants

Rust
1
pub fn enchants(&self) -> Result<Vec<Enchant>>

ItemStack::with_enchants

Rust
1
pub fn with_enchants(&self, enchants: &[Enchant]) -> Result<ItemStack>

Replaces the whole enchantment set and returns a new item.

  • Parameters:
    • enchants : &[Enchant]
  • Return type: Result<ItemStack>
  • Slots: item_set_enchants

ItemStack::matches

Rust
1
pub fn matches(&self, other: &ItemStack) -> Result<bool>

Whether two items are the same kind of thing.

The criterion comes from the engine, ItemStack::matches, and is not string equality: fields such as count and durability take no part, while comparing SNBT text would include them. A missing slot returns Err and does not fall back to a text comparison, which would make the criterion differ between hosts.

  • Parameters:
    • other : &ItemStack
  • Return type: Result<bool>
  • Slots: item_matches

Enchant

Rust
1
2
3
4
5
6
pub struct Enchant {
    /// The enchantment id. Whether the host reports a numeric id or a name depends on the
    /// BDS version, and it is carried through unchanged.
    pub id: String,
    pub level: i32,
}

One enchantment.

  • Implements: Debug, Clone, PartialEq, Eq