SPIGOT-6507: Introduce abstract skeleton and stray conversion

The previous layout and class hierarchy of the skeleton API defined
variances of the skeleton, such as the wither skeleton or the stray, as
child types of the normal skeleton variance, which is technically
incorrect, yet did not produce any specific issue as the normal skeleton
variance did not have any unique logic.

With the introduction of powdered snow in the 1.17 update, the normal
skeleton variance now has unique logic, specifically the conversion to
a stay when stuck inside powdered snow, which cannot be represented in
the current API layout due to the prior mentioned hierarchy.

This commit introduces the AbstractSkeleton interface, which follows the
concept of other abstract interfaces like AbstractArrow and serves as a
common parent to the existing skeleton variances. Furthermore this
commit introduces the previously mentioned stray conversion to the
normal skeleton variance.

This commit does not break ABI yet breaks backwards compatibility due to
the mentioned hierarchy changes. Plugins that previously used the
Skelton interface to compute whether or not an entity is skeleton-like
through instanceOf checks will now only match the normal skeleton variance
instead of any skeleton-like entity.

By: Bjarne Koll <lynxplay101@gmail.com>

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

@@ -0,0 +1,35 @@
+package org.bukkit.entity;
+
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * This interface defines or represents the abstract concept of skeleton-like
+ * entities on the server. The interface is hence not a direct representation
+ * of an entity but rather serves as a parent to interfaces/entity types like
+ * {@link Skeleton}, {@link WitherSkeleton} or {@link Stray}.
+ *
+ * To compute what specific type of skeleton is present in a variable/field
+ * of this type, instanceOf checks against the specific subtypes listed prior
+ * are recommended.
+ */
+public interface AbstractSkeleton extends Monster {
+
+    /**
+     * Gets the current type of this skeleton.
+     *
+     * @return Current type
+     * @deprecated should check what class instance this is.
+     */
+    @Deprecated
+    @NotNull
+    public Skeleton.SkeletonType getSkeletonType();
+
+    /**
+     * @param type type
+     * @deprecated Must spawn a new subtype variant
+     */
+    @Deprecated
+    @Contract("_ -> fail")
+    public void setSkeletonType(Skeleton.SkeletonType type);
+}

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

@@ -1,33 +1,52 @@
 package org.bukkit.entity;
 
-import org.jetbrains.annotations.Contract;
-import org.jetbrains.annotations.NotNull;
-
 /**
  * Represents a Skeleton.
+ * <p>
+ * This interface only represents the normal skeleton type on the server.
+ * Other skeleton-like entities, such as the {@link WitherSkeleton} or the
+ * {@link Stray} are not related to this type.
  */
-public interface Skeleton extends Monster {
+public interface Skeleton extends AbstractSkeleton {
 
     /**
-     * Gets the current type of this skeleton.
+     * Computes whether or not this skeleton is currently in the process of
+     * converting to a {@link Stray} due to it being frozen by powdered snow.
      *
-     * @return Current type
-     * @deprecated should check what class instance this is
+     * @return whether or not the skeleton is converting to a stray.
      */
-    @Deprecated
-    @NotNull
-    public SkeletonType getSkeletonType();
+    boolean isConverting();
 
     /**
-     * @param type type
-     * @deprecated Must spawn a new subtype variant
+     * Gets the amount of ticks until this entity will be converted to a stray
+     * as a result of being frozen by a powdered snow block.
+     * <p>
+     * When this reaches 0, the entity will be converted.
+     *
+     * @return the conversion time left represented in ticks.
+     *
+     * @throws IllegalStateException if {@link #isConverting()} is false.
      */
-    @Deprecated
-    @Contract("_ -> fail")
-    public void setSkeletonType(SkeletonType type);
+    int getConversionTime();
 
-    /*
-     * @deprecated classes are different types
+    /**
+     * Sets the amount of ticks until this entity will be converted to a stray
+     * as a result of being frozen by a powdered snow block.
+     * <p>
+     * When this reaches 0, the entity will be converted. A value of less than 0
+     * will stop the current conversion process without converting the current
+     * entity.
+     *
+     * @param time the new conversion time left before the conversion in ticks.
+     */
+    void setConversionTime(int time);
+
+    /**
+     * A legacy enum that defines the different variances of skeleton-like
+     * entities on the server.
+     *
+     * @deprecated classes are different types. This interface only remains in
+     *     the Skeleton interface to preserve backwards compatibility.
      */
     @Deprecated
     public enum SkeletonType {

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

@@ -1,6 +1,6 @@
 package org.bukkit.entity;
 
 /**
- * Represents a Stray - variant of {@link Skeleton}.
+ * Represents a Stray - variant of {@link AbstractSkeleton}.
  */
-public interface Stray extends Skeleton { }
+public interface Stray extends AbstractSkeleton { }

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

@@ -1,6 +1,6 @@
 package org.bukkit.entity;
 
 /**
- * Represents a WitherSkeleton - variant of {@link Skeleton}.
+ * Represents a WitherSkeleton - variant of {@link AbstractSkeleton}.
  */
-public interface WitherSkeleton extends Skeleton { }
+public interface WitherSkeleton extends AbstractSkeleton { }