Add Shearable API

paper-api/src/main/java/io/papermc/paper/entity/Shearable.java

@@ -0,0 +1,44 @@
+package io.papermc.paper.entity;
+
+import net.kyori.adventure.sound.Sound;
+import org.bukkit.entity.Entity;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Represents an entity that can be sheared.
+ */
+@NullMarked
+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(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();
+}

paper-api/src/main/java/org/bukkit/entity/Bogged.java

@@ -6,7 +6,7 @@ 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
 
     /**
      * Gets whether the bogged is in its sheared state.

paper-api/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

paper-api/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);
 }

paper-api/src/main/java/org/bukkit/entity/Sheep.java

@@ -5,7 +5,7 @@ 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
 
     /**
      * Gets whether the sheep is in its sheared state.

paper-api/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