Fix EntityEquipment and related javadocs (#7380)

2024-12-29 15:49:00 +01:00 · 2022-05-31 13:40:21 -07:00 · 2022-05-31 13:40:21 -07:00 · 67275a04a7
commit 67275a04a7
parent 04acf65b3c
3 changed files with 267 additions and 10 deletions
--- a/patches/api/Fix-Spigot-annotation-mistakes.patch
+++ b/patches/api/Fix-Spigot-annotation-mistakes.patch
@ -408,6 +408,19 @@ index 0000000000000000000000000000000000000000..00000000000000000000000000000000
 @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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
+--- a/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
+++ b/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
+@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
 --- a/src/main/java/org/bukkit/event/player/PlayerShowEntityEvent.java
@ -481,6 +494,18 @@ index 0000000000000000000000000000000000000000..00000000000000000000000000000000
 
     /**
      * 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
+--- a/src/main/java/org/bukkit/inventory/EntityEquipment.java
+++ b/src/main/java/org/bukkit/inventory/EntityEquipment.java
+@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
 --- a/src/main/java/org/bukkit/inventory/FurnaceRecipe.java
--- a/patches/api/Fix-upstream-javadocs.patch
+++ b/patches/api/Fix-upstream-javadocs.patch
@ -124,16 +124,248 @@ index 0000000000000000000000000000000000000000..00000000000000000000000000000000
      * @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
+diff --git a/src/main/java/org/bukkit/inventory/EntityEquipment.java b/src/main/java/org/bukkit/inventory/EntityEquipment.java
 index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
-+++ b/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
-@@ -0,0 +0,0 @@ public class PlayerMoveEvent extends PlayerEvent implements Cancellable {
+--- a/src/main/java/org/bukkit/inventory/EntityEquipment.java
+++ b/src/main/java/org/bukkit/inventory/EntityEquipment.java
+@@ -0,0 +0,0 @@ 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
+@@ -0,0 +0,0 @@ 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
+@@ -0,0 +0,0 @@ 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()
+@@ -0,0 +0,0 @@ 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();
+ 
+     /**
+@@ -0,0 +0,0 @@ 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();
+ 
+     /**
+@@ -0,0 +0,0 @@ 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();
+ 
+     /**
+@@ -0,0 +0,0 @@ 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();
+ 
+     /**
+@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
+--- a/src/main/java/org/bukkit/inventory/PlayerInventory.java
+++ b/src/main/java/org/bukkit/inventory/PlayerInventory.java
+@@ -0,0 +0,0 @@ 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
+@@ -0,0 +0,0 @@ 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
+@@ -0,0 +0,0 @@ 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/add-get-set-drop-chance-to-EntityEquipment.patch
+++ b/patches/api/add-get-set-drop-chance-to-EntityEquipment.patch
@ -10,7 +10,7 @@ index 0000000000000000000000000000000000000000..00000000000000000000000000000000
 +++ b/src/main/java/org/bukkit/inventory/EntityEquipment.java
@@ -0,0 +0,0 @@ public interface EntityEquipment {
      */
-     @Nullable
+     @NotNull // Paper
     Entity getHolder();
 +    // Paper start
 +    /**