PaperMC/patches/api/General-ItemMeta-fixes.patch

From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
From: Jake Potrebic <jake.m.potrebic@gmail.com>
Date: Tue, 28 May 2024 19:59:01 -0700
Subject: [PATCH] General ItemMeta fixes


diff --git a/src/main/java/org/bukkit/FireworkEffect.java b/src/main/java/org/bukkit/FireworkEffect.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/FireworkEffect.java
+++ b/src/main/java/org/bukkit/FireworkEffect.java
@@ -0,0 +0,0 @@ public final class FireworkEffect implements ConfigurationSerializable {
     private String string = null;
 
     FireworkEffect(boolean flicker, boolean trail, @NotNull ImmutableList<Color> colors, @NotNull ImmutableList<Color> fadeColors, @NotNull Type type) {
-        if (colors.isEmpty()) {
-            throw new IllegalStateException("Cannot make FireworkEffect without any color");
-        }
+        // Paper - can have empty colors
         this.flicker = flicker;
         this.trail = trail;
         this.colors = colors;
diff --git a/src/main/java/org/bukkit/inventory/ItemType.java b/src/main/java/org/bukkit/inventory/ItemType.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/ItemType.java
+++ b/src/main/java/org/bukkit/inventory/ItemType.java
@@ -0,0 +0,0 @@ import org.bukkit.inventory.meta.MapMeta;
 import org.bukkit.inventory.meta.MusicInstrumentMeta;
 import org.bukkit.inventory.meta.OminousBottleMeta;
 import org.bukkit.inventory.meta.PotionMeta;
+import org.bukkit.inventory.meta.ShieldMeta;
 import org.bukkit.inventory.meta.SkullMeta;
 import org.bukkit.inventory.meta.SpawnEggMeta;
 import org.bukkit.inventory.meta.SuspiciousStewMeta;
@@ -0,0 +0,0 @@ public interface ItemType extends Keyed, Translatable, net.kyori.adventure.trans
     /**
      * ItemMeta: {@link BlockStateMeta}
      */
-    ItemType.Typed<BlockStateMeta> SHIELD = getItemType("shield");
+    ItemType.Typed<ShieldMeta> SHIELD = getItemType("shield"); // Paper - update shield to its new meta
     ItemType.Typed<ItemMeta> TOTEM_OF_UNDYING = getItemType("totem_of_undying");
     ItemType.Typed<ItemMeta> SHULKER_SHELL = getItemType("shulker_shell");
     ItemType.Typed<ItemMeta> IRON_NUGGET = getItemType("iron_nugget");
diff --git a/src/main/java/org/bukkit/inventory/meta/CompassMeta.java b/src/main/java/org/bukkit/inventory/meta/CompassMeta.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/meta/CompassMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/CompassMeta.java
@@ -0,0 +0,0 @@ public interface CompassMeta extends ItemMeta {
     /**
      * Sets the location this lodestone compass will point to.
      *
-     * @param lodestone new location or null to clear
+     * @param lodestone new location or null to clear the targeted location
+     * @see #clearLodestone() to reset the compass to a normal compass
      */
     void setLodestone(@Nullable Location lodestone);
 
@@ -0,0 +0,0 @@ public interface CompassMeta extends ItemMeta {
      * location.
      *
      * @param tracked new tracked status
+     * @see #clearLodestone() to reset the compass to a normal compass
      */
     void setLodestoneTracked(boolean tracked);
 
+    // Paper start - Add more lodestone compass methods
+    /**
+     * Checks if this compass is considered a lodestone compass.
+     * @see #hasLodestone() to check if a position is being tracked
+     * @see #isLodestoneTracked() to check if it verifies the position is a lodestone
+     */
+    boolean isLodestoneCompass();
+
+    /**
+     * Reset this compass to a normal compass, removing any tracked
+     * location.
+     */
+    void clearLodestone();
+    // Paper end - Add more lodestone compass methods
+
     @Override
     CompassMeta clone();
 }
diff --git a/src/main/java/org/bukkit/inventory/meta/Damageable.java b/src/main/java/org/bukkit/inventory/meta/Damageable.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/meta/Damageable.java
+++ b/src/main/java/org/bukkit/inventory/meta/Damageable.java
@@ -0,0 +0,0 @@ import org.jetbrains.annotations.Nullable;
 public interface Damageable extends ItemMeta {
 
     /**
-     * Checks to see if this item has damage
+     * Checks to see if this item has damage greater than 0.
      *
-     * @return true if this has damage
+     * @return true if this has damage > 0
      */
     boolean hasDamage();
 
     /**
      * Gets the damage
+     * <p>
+     * Call {@link #hasDamageValue()} to be sure
+     * a damage value is set.
      *
      * @return the damage
      */
@@ -0,0 +0,0 @@ public interface Damageable extends ItemMeta {
      * Sets the damage
      *
      * @param damage item damage
+     * @see #resetDamage() to reset and clear the damage data component
      */
     void setDamage(int damage);
 
+    // Paper start
+    /**
+     * Checks if any damage value, including 0,
+     * is set on this meta.
+     *
+     * @return true if any value is set
+     */
+    boolean hasDamageValue();
+
+    /**
+     * Clears the damage component from the meta. Differs
+     * from {@code setDamage(0)} in that it removes the component
+     * instead of adding the component with a value of 0.
+     */
+    void resetDamage();
+    // Paper end
+
     /**
      * Checks to see if this item has a maximum amount of damage.
      *
diff --git a/src/main/java/org/bukkit/inventory/meta/FireworkMeta.java b/src/main/java/org/bukkit/inventory/meta/FireworkMeta.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/meta/FireworkMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/FireworkMeta.java
@@ -0,0 +0,0 @@ public interface FireworkMeta extends ItemMeta {
      */
     boolean hasEffects();
 
+    // Paper start - add hasPower
+    /**
+     * Checks if power is defined on this meta.
+     *
+     * @return true if there is a power specified
+     */
+    boolean hasPower();
+    // Paper end - add hasPower
+
     /**
      * Gets the approximate height the firework will fly.
      *
      * @return approximate flight height of the firework.
+     * @see #hasPower()
      */
     int getPower();
 
diff --git a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
@@ -0,0 +0,0 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
 
     /**
      * Set all {@link Attribute}s and their {@link AttributeModifier}s.
-     * To clear all currently set Attributes and AttributeModifiers use
-     * null or an empty Multimap.
+     * To clear all custom attribute modifiers, use {@code null}. To set
+     * no modifiers (which will override the default modifiers), use an
+     * empty map.
      * If not null nor empty, this will filter all entries that are not-null
      * and add them to the ItemStack.
      *