From 6a59a19dde9df7fe8b0cc002f57439f38f441f96 Mon Sep 17 00:00:00 2001 From: Bukkit/Spigot Date: Mon, 14 Jun 2021 10:00:57 +1000 Subject: [PATCH] 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 --- .../org/bukkit/entity/AbstractSkeleton.java | 35 ++++++++++++ .../main/java/org/bukkit/entity/Skeleton.java | 53 +++++++++++++------ .../main/java/org/bukkit/entity/Stray.java | 4 +- .../org/bukkit/entity/WitherSkeleton.java | 4 +- 4 files changed, 75 insertions(+), 21 deletions(-) create mode 100644 paper-api/src/main/java/org/bukkit/entity/AbstractSkeleton.java diff --git a/paper-api/src/main/java/org/bukkit/entity/AbstractSkeleton.java b/paper-api/src/main/java/org/bukkit/entity/AbstractSkeleton.java new file mode 100644 index 0000000000..e2fce218c6 --- /dev/null +++ b/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); +} diff --git a/paper-api/src/main/java/org/bukkit/entity/Skeleton.java b/paper-api/src/main/java/org/bukkit/entity/Skeleton.java index 16b1293887..01d838a60d 100644 --- a/paper-api/src/main/java/org/bukkit/entity/Skeleton.java +++ b/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. + *

+ * 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. + *

+ * 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. + *

+ * 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 { diff --git a/paper-api/src/main/java/org/bukkit/entity/Stray.java b/paper-api/src/main/java/org/bukkit/entity/Stray.java index 9c83f98e91..a1427e585b 100644 --- a/paper-api/src/main/java/org/bukkit/entity/Stray.java +++ b/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 { } diff --git a/paper-api/src/main/java/org/bukkit/entity/WitherSkeleton.java b/paper-api/src/main/java/org/bukkit/entity/WitherSkeleton.java index 7045014e60..78971bffe2 100644 --- a/paper-api/src/main/java/org/bukkit/entity/WitherSkeleton.java +++ b/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 { }