Fix EntityEquipment and related javadocs (#7380)

2024-12-22 08:57:35 +01:00 · 2022-05-31 13:40:21 -07:00 · 2022-05-31 13:40:21 -07:00 · 3f7111d4e1
commit 3f7111d4e1
parent f210f67c4a
3 changed files with 271 additions and 14 deletions
--- a/patches/api/0054-Fix-upstream-javadocs.patch
+++ b/patches/api/0054-Fix-upstream-javadocs.patch
@ -124,16 +124,248 @@ index 1119e26e270bb45f517955b19d95a9ec3d113634..4631647c64c89ffdde2d9b63bdab974a
      * @param sz The new size of the slime.
      */
     public void setSize(int sz);
-diff --git a/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java b/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
-index 1b2267f4e8ebded198773ec80e2bff2c861c7084..1a58734d919fae247eeb85dd785fd59990856505 100644
--- a/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
-+++ b/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
-@@ -78,7 +78,7 @@ public class PlayerMoveEvent extends PlayerEvent implements Cancellable {
+diff --git a/src/main/java/org/bukkit/inventory/EntityEquipment.java b/src/main/java/org/bukkit/inventory/EntityEquipment.java
+index d5b50a4a954fed35d37f03f1a277cc173ca106df..a91fa5386afd7a1137adb921ad5adb798604772f 100644
+--- a/src/main/java/org/bukkit/inventory/EntityEquipment.java
+++ b/src/main/java/org/bukkit/inventory/EntityEquipment.java
+@@ -37,9 +37,23 @@ public interface EntityEquipment {
+     public ItemStack getItem(@NotNull EquipmentSlot slot);
+ 
+     /**
+-     * Gets a copy of the item the entity is currently holding
+     * Gets the item the entity is currently holding
+      * in their main hand.
      *
-      * @return Location the player moved to
+     * <p>
+     * This returns a copy if this equipment instance is from a non-player,
+     * or it's an empty stack (has AIR as its type).
+     * For non-empty stacks from players, this returns a live mirror. You can check if this
+     * will return a mirror with
+     * <pre>{@code
+     * EntityEquipment equipment = entity.getEquipment();
+     * if (equipment instanceof PlayerInventory) {
+     *     equipment.getItemInMainHand(); // will return a mirror
+     * } else {
+     *     equipment.getItemInMainHand(); // will return a copy
+     * }
+     * }</pre>
+     *
+      * @return the currently held item
+      */
+     @NotNull
+@@ -61,9 +75,23 @@ public interface EntityEquipment {
+     void setItemInMainHand(@Nullable ItemStack item, boolean silent);
+ 
+     /**
+-     * Gets a copy of the item the entity is currently holding
+     * Gets the item the entity is currently holding
+      * in their off hand.
+      *
+     * <p>
+     * This returns a copy if this equipment instance is from a non-player,
+     * or it's an empty stack (has AIR as its type).
+     * For non-empty stacks from players, this returns a live mirror. You can check if this
+     * will return a mirror with
+     * <pre>{@code
+     * EntityEquipment equipment = entity.getEquipment();
+     * if (equipment instanceof PlayerInventory) {
+     *     equipment.getItemInOffHand(); // will return a mirror
+     * } else {
+     *     equipment.getItemInOffHand(); // will return a copy
+     * }
+     * }</pre>
+     *
+      * @return the currently held item
+      */
+     @NotNull
+@@ -85,7 +113,21 @@ public interface EntityEquipment {
+     void setItemInOffHand(@Nullable ItemStack item, boolean silent);
+ 
+     /**
+-     * Gets a copy of the item the entity is currently holding
+     * Gets the item the entity is currently holding
+     *
+     * <p>
+     * This returns a copy if this equipment instance is from a non-player,
+     * or it's an empty stack (has AIR as its type).
+     * For non-empty stacks from players, this returns a live mirror. You can check if this
+     * will return a mirror with
+     * <pre>{@code
+     * EntityEquipment equipment = entity.getEquipment();
+     * if (equipment instanceof PlayerInventory) {
+     *     equipment.getItemInHand(); // will return a mirror
+     * } else {
+     *     equipment.getItemInHand(); // will return a copy
+     * }
+     * }</pre>
+      *
+      * @return the currently held item
+      * @see #getItemInMainHand()
+@@ -110,11 +152,24 @@ public interface EntityEquipment {
+     void setItemInHand(@Nullable ItemStack stack);
+ 
+     /**
+-     * Gets a copy of the helmet currently being worn by the entity
+     * Gets the helmet currently being worn by the entity
+     *
+     * <p>
+     * This returns a copy if this equipment instance is from a non-player.
+     * For stacks from players, this returns a live mirror (or null). You can check if this
+     * will return a mirror with
+     * <pre>{@code
+     * EntityEquipment equipment = entity.getEquipment();
+     * if (equipment instanceof PlayerInventory) {
+     *     equipment.getItemInHand(); // will return a mirror
+     * } else {
+     *     equipment.getItemInHand(); // will return a copy
+     * }
+     * }</pre>
+      *
+      * @return The helmet being worn
      */
 -    @Nullable
-+    @NotNull // Paper
-     public Location getTo() {
-         return to;
-     }
+    @org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
+     ItemStack getHelmet();
+ 
+     /**
+@@ -133,11 +188,24 @@ public interface EntityEquipment {
+     void setHelmet(@Nullable ItemStack helmet, boolean silent);
+ 
+     /**
+-     * Gets a copy of the chest plate currently being worn by the entity
+     * Gets the chest plate currently being worn by the entity
+     *
+     * <p>
+     * This returns a copy if this equipment instance is from a non-player.
+     * For stacks from players, this returns a live mirror (or null). You can check if this
+     * will return a mirror with
+     * <pre>{@code
+     * EntityEquipment equipment = entity.getEquipment();
+     * if (equipment instanceof PlayerInventory) {
+     *     equipment.getChestplate(); // will return a mirror
+     * } else {
+     *     equipment.getChestplate(); // will return a copy
+     * }
+     * }</pre>
+      *
+      * @return The chest plate being worn
+      */
+-    @Nullable
+    @org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
+     ItemStack getChestplate();
+ 
+     /**
+@@ -156,11 +224,24 @@ public interface EntityEquipment {
+     void setChestplate(@Nullable ItemStack chestplate, boolean silent);
+ 
+     /**
+-     * Gets a copy of the leggings currently being worn by the entity
+     * Gets the leggings currently being worn by the entity
+     *
+     * <p>
+     * This returns a copy if this equipment instance is from a non-player.
+     * For stacks from players, this returns a live mirror (or null). You can check if this
+     * will return a mirror with
+     * <pre>{@code
+     * EntityEquipment equipment = entity.getEquipment();
+     * if (equipment instanceof PlayerInventory) {
+     *     equipment.getLeggings(); // will return a mirror
+     * } else {
+     *     equipment.getLeggings(); // will return a copy
+     * }
+     * }</pre>
+      *
+      * @return The leggings being worn
+      */
+-    @Nullable
+    @org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
+     ItemStack getLeggings();
+ 
+     /**
+@@ -179,11 +260,24 @@ public interface EntityEquipment {
+     void setLeggings(@Nullable ItemStack leggings, boolean silent);
+ 
+     /**
+-     * Gets a copy of the boots currently being worn by the entity
+     * Gets the boots currently being worn by the entity
+     *
+     * <p>
+     * This returns a copy if this equipment instance is from a non-player.
+     * For stacks from players, this returns a live mirror (or null). You can check if this
+     * will return a mirror with
+     * <pre>{@code
+     * EntityEquipment equipment = entity.getEquipment();
+     * if (equipment instanceof PlayerInventory) {
+     *     equipment.getBoots(); // will return a mirror
+     * } else {
+     *     equipment.getBoots(); // will return a copy
+     * }
+     * }</pre>
+      *
+      * @return The boots being worn
+      */
+-    @Nullable
+    @org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
+     ItemStack getBoots();
+ 
+     /**
+@@ -202,12 +296,25 @@ public interface EntityEquipment {
+     void setBoots(@Nullable ItemStack boots, boolean silent);
+ 
+     /**
+-     * Gets a copy of all worn armor
+     * Gets all worn armor
+     *
+     * <p>
+     * This returns a copy if this equipment instance is from a non-player,
+     * or it's an empty stack (has AIR as its type).
+     * For non-empty stacks from players, this returns a live mirror. You can check if this
+     * will return a mirror with
+     * <pre>{@code
+     * EntityEquipment equipment = entity.getEquipment();
+     * if (equipment instanceof PlayerInventory) {
+     *     equipment.getArmorContents(); // will return an array of mirror
+     * } else {
+     *     equipment.getArmorContents(); // will return an array of copies
+     * }
+     * }</pre>
+      *
+      * @return The array of worn armor. Individual items may be null.
+      */
+-    @NotNull
+-    ItemStack[] getArmorContents();
+    @org.bukkit.UndefinedNullability("not null elements for entities, nullable elements for players") ItemStack @NotNull [] getArmorContents(); // Paper
+ 
+     /**
+      * Sets the entities armor to the provided array of ItemStacks
+diff --git a/src/main/java/org/bukkit/inventory/PlayerInventory.java b/src/main/java/org/bukkit/inventory/PlayerInventory.java
+index 62fbd7f6d8195bebcab7f704a0a485a1bbeca26c..5461f7fa75f5a065bb333b4a113640b5fe1e3825 100644
+--- a/src/main/java/org/bukkit/inventory/PlayerInventory.java
+++ b/src/main/java/org/bukkit/inventory/PlayerInventory.java
+@@ -158,7 +158,7 @@ public interface PlayerInventory extends Inventory {
+     public void setBoots(@Nullable ItemStack boots);
+ 
+     /**
+-     * Gets a copy of the item the player is currently holding
+     * Gets the item the player is currently holding
+      * in their main hand.
+      *
+      * @return the currently held item
+@@ -174,7 +174,7 @@ public interface PlayerInventory extends Inventory {
+     void setItemInMainHand(@Nullable ItemStack item);
+ 
+     /**
+-     * Gets a copy of the item the player is currently holding
+     * Gets the item the player is currently holding
+      * in their off hand.
+      *
+      * @return the currently held item
+@@ -190,7 +190,7 @@ public interface PlayerInventory extends Inventory {
+     void setItemInOffHand(@Nullable ItemStack item);
+ 
+     /**
+-     * Gets a copy of the item the player is currently holding
+     * Gets the item the player is currently holding
+      *
+      * @return the currently held item
+      * @see #getItemInMainHand()
--- a/patches/api/0175-Fix-Spigot-annotation-mistakes.patch
+++ b/patches/api/0175-Fix-Spigot-annotation-mistakes.patch
@ -408,6 +408,19 @@ index d8a73cd22268e90eb438f522b9019f826f343275..78869fdb9cf4c541dff7d67b51866914
 @Warning(false)
 public class PlayerHideEntityEvent extends PlayerEvent {
 
+diff --git a/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java b/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
+index 1b2267f4e8ebded198773ec80e2bff2c861c7084..1a58734d919fae247eeb85dd785fd59990856505 100644
+--- a/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
+++ b/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
+@@ -78,7 +78,7 @@ public class PlayerMoveEvent extends PlayerEvent implements Cancellable {
+      *
+      * @return Location the player moved to
+      */
+-    @Nullable
+    @NotNull // Paper
+     public Location getTo() {
+         return to;
+     }
 diff --git a/src/main/java/org/bukkit/event/player/PlayerShowEntityEvent.java b/src/main/java/org/bukkit/event/player/PlayerShowEntityEvent.java
 index 5408a8c123942a56ef11597ae6cdb77e14f741e3..29bb84145be18ef9162abdfc8820f2b3f7fd0db5 100644
 --- a/src/main/java/org/bukkit/event/player/PlayerShowEntityEvent.java
@ -481,6 +494,18 @@ index df81bac9ecff697f98941e5c8490e10391e90090..a32977ba3ba60a1c9aee6e469d5d6cd1
 
     /**
      * Get the current recipe formed on the crafting inventory, if any.
+diff --git a/src/main/java/org/bukkit/inventory/EntityEquipment.java b/src/main/java/org/bukkit/inventory/EntityEquipment.java
+index a91fa5386afd7a1137adb921ad5adb798604772f..42f76751ec414648ee719c341d471d947bf85be6 100644
+--- a/src/main/java/org/bukkit/inventory/EntityEquipment.java
+++ b/src/main/java/org/bukkit/inventory/EntityEquipment.java
+@@ -511,6 +511,6 @@ public interface EntityEquipment {
+      *
+      * @return the entity this EntityEquipment belongs to
+      */
+-    @Nullable
+    @NotNull // Paper
+     Entity getHolder();
+ }
 diff --git a/src/main/java/org/bukkit/inventory/FurnaceRecipe.java b/src/main/java/org/bukkit/inventory/FurnaceRecipe.java
 index 1d442dc16cbb0fed21714d47007f3f11e30c57d4..af8f7b88edf0fa790edcf16356a030c4834f531e 100644
 --- a/src/main/java/org/bukkit/inventory/FurnaceRecipe.java
@ -602,7 +627,7 @@ index 487e6a6391123a4792c3bdeba869aa2bcb5922cc..46bf24aed3e959d216d94603560cb75a
         return this.meta == null ? Bukkit.getItemFactory().getItemMeta(this.type) : this.meta.clone();
     }
 diff --git a/src/main/java/org/bukkit/inventory/PlayerInventory.java b/src/main/java/org/bukkit/inventory/PlayerInventory.java
-index 62fbd7f6d8195bebcab7f704a0a485a1bbeca26c..8b5385e39f64c4df8e235a8832d91e55642421ce 100644
+index 5461f7fa75f5a065bb333b4a113640b5fe1e3825..c4d657727e508cb941320730a9d3aa5486712ef3 100644
 --- a/src/main/java/org/bukkit/inventory/PlayerInventory.java
 +++ b/src/main/java/org/bukkit/inventory/PlayerInventory.java
@@ -14,8 +14,7 @@ public interface PlayerInventory extends Inventory {
--- a/patches/api/0282-add-get-set-drop-chance-to-EntityEquipment.patch
+++ b/patches/api/0282-add-get-set-drop-chance-to-EntityEquipment.patch
@ -5,12 +5,12 @@ Subject: [PATCH] add get-set drop chance to EntityEquipment


 diff --git a/src/main/java/org/bukkit/inventory/EntityEquipment.java b/src/main/java/org/bukkit/inventory/EntityEquipment.java
-index d5b50a4a954fed35d37f03f1a277cc173ca106df..3f2f5beadfd6df0aaab5853783001ec2cca7a819 100644
+index ac9e606b85e0715b7e1b331a987c0ee34ee541ff..7b21e913a3ac9beb5dab91f11b1a0aa62e33ad36 100644
 --- a/src/main/java/org/bukkit/inventory/EntityEquipment.java
 +++ b/src/main/java/org/bukkit/inventory/EntityEquipment.java
-@@ -406,4 +406,32 @@ public interface EntityEquipment {
+@@ -513,4 +513,32 @@ public interface EntityEquipment {
      */
-     @Nullable
+     @NotNull // Paper
     Entity getHolder();
 +    // Paper start
 +    /**