Update launchProjectile API (#11300)

patches/api/0390-Add-Shearable-API.patch

@@ -0,0 +1,138 @@
+From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
+From: Owen1212055 <23108066+Owen1212055@users.noreply.github.com>
+Date: Sun, 17 Oct 2021 15:39:41 -0400
+Subject: [PATCH] Add Shearable API
+
+
+diff --git a/src/main/java/io/papermc/paper/entity/Shearable.java b/src/main/java/io/papermc/paper/entity/Shearable.java
+new file mode 100644
+index 0000000000000000000000000000000000000000..0d5793790ab6a47525ad33033517361205756338
+--- /dev/null
++++ b/src/main/java/io/papermc/paper/entity/Shearable.java
+@@ -0,0 +1,43 @@
++package io.papermc.paper.entity;
++
++import net.kyori.adventure.sound.Sound;
++import org.bukkit.entity.Entity;
++import org.jetbrains.annotations.NotNull;
++
++/**
++ * Represents an entity that can be sheared.
++ */
++public interface Shearable extends Entity {
++
++    /**
++     * Forces the entity to be sheared and then play the effect as if it were sheared by a player.
++     * This will cause the entity to be sheared, even if {@link Shearable#readyToBeSheared()} is false.
++     * <p>
++     * Some shearing behavior may cause the entity to no longer be valid
++     * due to it being replaced by a different entity.
++     */
++    default void shear() {
++        this.shear(Sound.Source.PLAYER);
++    }
++
++    /**
++     * Forces the entity to be sheared and then play the effect as if it were sheared by the provided source.
++     * This will cause the entity to be sheared, even if {@link Shearable#readyToBeSheared()} is false.
++     * <p>
++     * Some shearing behavior may cause the entity to no longer be valid
++     * due to it being replaced by a different entity.
++     * <p>
++     * This simulates the behavior of an actual shearing, which may cause events like EntityTransformEvent to be called
++     * for mooshrooms, and EntityDropItemEvent to be called for sheep.
++     *
++     * @param source Sound source to play any sound effects on
++     */
++    void shear(@NotNull Sound.Source source);
++
++    /**
++     * Gets if the entity would be able to be sheared or not naturally using shears.
++     *
++     * @return if the entity can be sheared
++     */
++    boolean readyToBeSheared();
++}
+diff --git a/src/main/java/org/bukkit/entity/Bogged.java b/src/main/java/org/bukkit/entity/Bogged.java
+index 8b75a505a55a96a5795ac31a2d37307add12cd9e..6296a6f3f3e794677fd3a626376f357c740ec356 100644
+--- a/src/main/java/org/bukkit/entity/Bogged.java
++++ b/src/main/java/org/bukkit/entity/Bogged.java
+@@ -6,5 +6,5 @@ import org.jetbrains.annotations.ApiStatus;
+  * Represents a Bogged Skeleton.
+  */
+ @ApiStatus.Experimental
+-public interface Bogged extends AbstractSkeleton, Shearable {
++public interface Bogged extends AbstractSkeleton, Shearable, io.papermc.paper.entity.Shearable { // Paper - Shear API
+ }
+diff --git a/src/main/java/org/bukkit/entity/MushroomCow.java b/src/main/java/org/bukkit/entity/MushroomCow.java
+index cef1700834643fe28ed5737578d91ecefbe99e2f..86c0043ef4e1288b6fe2f68a9b6d01c3de2c3454 100644
+--- a/src/main/java/org/bukkit/entity/MushroomCow.java
++++ b/src/main/java/org/bukkit/entity/MushroomCow.java
+@@ -8,7 +8,7 @@ import org.jetbrains.annotations.NotNull;
+ /**
+  * Represents a mushroom {@link Cow}
+  */
+-public interface MushroomCow extends Cow {
++public interface MushroomCow extends Cow, io.papermc.paper.entity.Shearable { // Paper
+ 
+     /**
+      * Checks for the presence of custom potion effects to be applied to the
+diff --git a/src/main/java/org/bukkit/entity/Shearable.java b/src/main/java/org/bukkit/entity/Shearable.java
+index 0215d20f81bfbef080f86ce46147a38f71310f65..9967c8a52ddd2c7e10db49a3f166731373f1ba45 100644
+--- a/src/main/java/org/bukkit/entity/Shearable.java
++++ b/src/main/java/org/bukkit/entity/Shearable.java
+@@ -2,20 +2,30 @@ package org.bukkit.entity;
+ 
+ /**
+  * Represents an entity which can be shorn with shears.
++ * @deprecated Spigots shearable API miserably fails at capturing all entities that may be sheared by a player, like
++ * mushroom cows which, once sheared, convert into normal cows. For such entities, methods like
++ * {@link #setSheared(boolean)} or {@link #isSheared()} make no sense, making this API and interface dead API from
++ * the get-go.
+  */
++@Deprecated(forRemoval = true, since = "1.21")
+ public interface Shearable {
+ 
+     /**
+      * Gets whether the entity is in its sheared state.
+      *
+      * @return Whether the entity is sheared.
++     * @deprecated Use {@link io.papermc.paper.entity.Shearable#readyToBeSheared()} instead.
+      */
++    @Deprecated(forRemoval = true, since = "1.21")
+     boolean isSheared();
+ 
+     /**
+      * Sets whether the entity is in its sheared state.
+      *
+      * @param flag Whether to shear the entity
++     * @deprecated Use {@link io.papermc.paper.entity.Shearable#shear()} instead if applicable.
++     * Some entities cannot be "unsheared".
+      */
++    @Deprecated(forRemoval = true, since = "1.21")
+     void setSheared(boolean flag);
+ }
+diff --git a/src/main/java/org/bukkit/entity/Sheep.java b/src/main/java/org/bukkit/entity/Sheep.java
+index 46bc1a0ed9ee320c68a38362c1fa1f31319f01d8..01a0e5b1bb18d7a28d68329c2e2ab78a8df45f8e 100644
+--- a/src/main/java/org/bukkit/entity/Sheep.java
++++ b/src/main/java/org/bukkit/entity/Sheep.java
+@@ -5,5 +5,5 @@ import org.bukkit.material.Colorable;
+ /**
+  * Represents a Sheep.
+  */
+-public interface Sheep extends Animals, Colorable, Shearable {
++public interface Sheep extends Animals, Colorable, Shearable, io.papermc.paper.entity.Shearable { // Paper - Shear API
+ }
+diff --git a/src/main/java/org/bukkit/entity/Snowman.java b/src/main/java/org/bukkit/entity/Snowman.java
+index 10f8f6d45ae9280651c3ebddd1f90acbd7d6ff29..7fbfdb07585c7b28acea1f0c1f58ada0cc744441 100644
+--- a/src/main/java/org/bukkit/entity/Snowman.java
++++ b/src/main/java/org/bukkit/entity/Snowman.java
+@@ -5,7 +5,7 @@ import com.destroystokyo.paper.entity.RangedEntity;
+ /**
+  * Represents a snowman entity
+  */
+-public interface Snowman extends Golem, RangedEntity { // Paper
++public interface Snowman extends Golem, RangedEntity, io.papermc.paper.entity.Shearable { // Paper
+ 
+     /**
+      * Gets whether this snowman is in "derp mode", meaning it is not wearing a