1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
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..3991f2aa530c588f52e1f596d3b03743e8a8ecc4
--- /dev/null
+++ b/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();
+}
diff --git a/src/main/java/org/bukkit/entity/Bogged.java b/src/main/java/org/bukkit/entity/Bogged.java
index 0e5aaf54df0a5d0995147a905daef52442b070c5..6093b1dad8ad48708267a83bf4c1ad20467b3cf9 100644
--- a/src/main/java/org/bukkit/entity/Bogged.java
+++ b/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.
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 9ed473e5e993ef2d9558fe18bbcea7dad9b42994..f67f478945a7ba99bf72601678a153553526799a 100644
--- a/src/main/java/org/bukkit/entity/Sheep.java
+++ b/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.
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
|
