Add utility function to ItemStack for creating custom PlayerHeads

crates/valence_protocol/src/item.rs

@@ -1,7 +1,8 @@
 use std::io::Write;
 
+use uuid::Uuid;
 pub use valence_generated::item::ItemKind;
-use valence_nbt::Compound;
+use valence_nbt::{compound, Compound, List};
 
 use crate::{Decode, Encode};
 
@@ -43,6 +44,95 @@ impl ItemStack {
  self
  }
 
+ /// This function takes the "Value" of the skin you want to apply to a
+ /// PlayerHead. The "Value" is a Base64-encoded JSON object that is
+ /// usually provided by websites. To learn more: <https://minecraft.wiki/w/Item_format#Player_Heads>
+ ///
+ /// # Errors
+ /// This function returns an error if the [ItemStack] you call it on isn't a
+ /// PlayerHead
+ ///
+ /// # Examples
+ /// ```
+ /// // Value provided by https://minecraft-heads.com/
+ /// let value = "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNzlmOWRkOGQ5MjQ0NTg0NWIwODM1MmZjMmY0OTRjYTE4OGJmNWMzNzFmM2JmOWQwMWJiNzRkOGVlNTk3YmM1YSJ9fX0=";
+ /// let head = ItemStack::new(ItemKind::PlayerHead, 1, None).with_playerhead_texture_value(value).unwrap();
+ /// ```
+ ///
+ /// Simple head command. More examples of Valence's command system: <https://github.com/valence-rs/valence/blob/main/examples/command.rs>
+ /// ```
+ /// #[derive(Command)]
+ /// #[paths("head {username}")]
+ /// struct HeadCommand {
+ /// username: String,
+ /// }
+ ///
+ /// fn command_handler(
+ /// mut command_events: EventReader<CommandResultEvent<HeadCommand>>,
+ /// mut clients_query: Query<(&mut Client, &Username, &Properties, &mut Inventory)>,
+ /// ) {
+ /// for event in command_events.read() {
+ /// let target_username = &event.result.username;
+ ///
+ /// let target = if !target_username.is_empty() {
+ /// clients_query
+ /// .iter()
+ /// .find(|(_, username, _, _)| username.0 == *target_username)
+ /// } else {
+ /// Some(clients_query.get(event.executor).unwrap())
+ /// };
+ ///
+ /// if let Some(target) = target {
+ /// let properties = target.2;
+ /// let textures = properties.textures().unwrap();
+ ///
+ /// // Construct a PlayerHead using `with_playerhead_texture_value`
+ /// let head = ItemStack::new(ItemKind::PlayerHead, 1, None)
+ /// .with_playerhead_texture_value(textures.value.clone())
+ /// .unwrap();
+ ///
+ /// let (_, _, _, mut inventory) = clients_query.get_mut(event.executor).unwrap();
+ /// inventory.set_slot(36, head);
+ /// } else {
+ /// let (mut client, _, _, _) = clients_query.get_mut(event.executor).unwrap();
+ /// client.send_chat_message(
+ /// "No player with that username found on the server".color(Color::RED),
+ /// );
+ /// }
+ /// }
+ /// }
+ /// ```
+ #[must_use]
+ pub fn with_playerhead_texture_value(
+ mut self,
+ texture_value: impl Into<String>,
+ ) -> Result<Self, ()> {
+ if self.item != ItemKind::PlayerHead {
+ return Err(());
+ }
+
+ let new_nbt = compound! {
+ "SkullOwner" => compound! {
+ "Id" => Uuid::default(),
+ "Properties" => compound! {
+ "textures" => List::Compound(vec![
+ compound! {
+ "Value" => texture_value.into()
+ }
+ ])
+ }
+ }
+ };
+
+ if let Some(nbt) = &mut self.nbt {
+ nbt.merge(new_nbt);
+ } else {
+ self.nbt = Some(new_nbt);
+ }
+
+ Ok(self)
+ }
+
  pub const fn is_empty(&self) -> bool {
  matches!(self.item, ItemKind::Air) || self.count <= 0
  }