Package com.github.crashdemons.playerheads.compatibility

Interface CompatibilityProvider

  • public interface CompatibilityProvider
    An interface specifying all of the methods we need for our plugin that require differing Bukkit-specific implementations which we wish to abstract from our plugin code. CompatibilityProviders not only must implement this interface, but in order to be automatically selected by the Compatibility class, they must exist in a specific package name. Providers (or a class extending them) are expected to exist in the same package as the compatibility library (com.github.crashdemons.playerheads.compatibility by default). followed by the server type name and major/minor version. For example: com.github.crashdemons.playerheads.compatibility.craftbukkit_1_16 the class in this package must be named "Provider" and must not be abstract. Secondly, to be automatically selected by the Compatibility class, the server type and version must be listed in the CompatibilitySupport class' VERSIONS map. This is typically accomplished by replacing it in the compatibility-library module when shading in all relevant support classes (ie: the original is excluded from shading).
    Author:
    crashdemons (crashenator at gmail.com)

    • Method Detail

      • getType

        String getType()
        Retrieve the server type the provider implements code for.
        Returns:
        the server type string

      • getVersion

        String getVersion()
        Retrieve the version string associated with the specific Compatibility Provider implementation.
        Returns:
        the version string

      • getOwningPlayerDirect

        @Deprecated
OfflinePlayer getOwningPlayerDirect​(SkullMeta skullItemMeta)
        Deprecated.
        This method does not include extended checking, you probably dont want the direct method.
        Gets the owning player of a skull as direct as possible from the relevant API - this may not always reliably get the player. This method may not result in the same information as getOwner, you should check both.
        Parameters:
        skullItemMeta - the ItemMeta of the skull
        Returns:
        the player owning the skull, or null if none could be retrieved.

      • getOwningPlayerDirect

        @Deprecated
OfflinePlayer getOwningPlayerDirect​(Skull skullBlockState)
        Deprecated.
        This method does not include extended checking, you probably dont want the direct method.
        Gets the owning player of a skull as direct as possible from the relevant API - this may not always reliably get the player. This method may not result in the same information as getOwner, you should check both.
        Parameters:
        skullBlockState - the BlockState of the skull
        Returns:
        the player owning the skull, or null if none could be retrieved.

      • getOwningPlayer

        OfflinePlayer getOwningPlayer​(SkullMeta skullItemMeta)
        Gets the owning player of a skull, with an additional attempt to derive the player from Profile uuid. This method may not result in the same information as getOwner, you should check both. This method does not exhaustively attempt to derive players from usernames.
        Parameters:
        skullItemMeta - the ItemMeta of the skull
        Returns:
        the player owning the skull, or null if none could be retrieved.

      • getOwningPlayer

        OfflinePlayer getOwningPlayer​(Skull skullBlockState)
        Gets the owning player of a skull, with an additional attempt to derive the player from Profile uuid. This method may not result in the same information as getOwner, you should check both. This method does not exhaustively attempt to derive players from usernames.
        Parameters:
        skullBlockState - the BlockState of the skull
        Returns:
        the player owning the skull, or null if none could be retrieved.

      • getOwnerDirect

        @Deprecated
String getOwnerDirect​(SkullMeta skullItemMeta)
        Deprecated.
        This method does not include extended checking, you probably dont want the direct method.
        Gets the owner username of a skull as direct as possible from the relevant API - this may not always reliably get the username. This method may not result in the same information as getOwningPlayerDirect, you should check both.
        Parameters:
        skullItemMeta - the ItemMeta of the skull
        Returns:
        the owner name

      • getOwnerDirect

        @Deprecated
String getOwnerDirect​(Skull skullBlockState)
        Deprecated.
        This method does not include extended checking, you probably dont want the direct method.
        Gets the owner username of a skull as direct as possible from the relevant API - this may not always reliably get the username. This method may not result in the same information as getOwningPlayerDirect, you should check both.
        Parameters:
        skullBlockState - the BlockState of the skull
        Returns:
        the owner name

      • getOwner

        String getOwner​(SkullMeta skullItemMeta)
        Gets the owner username of a skull by any means necessary. Because of differing results between getOwningPlayer().getName() and getOwnerDirect(), it may be necessary to use both or check the profile field, which this method should do. This method must be implemented with the following defined order: getOwningPlayer and getProfilePlayer if necessary to check name, then getOwner to check name.
        Parameters:
        skullItemMeta - the itemmeta of the skull to check
        Returns:
        the owner name or null if none could be found.

      • getOwner

        String getOwner​(Skull skullBlockState)
        Gets the owner username of a skull by any means necessary. Because of differing results between getOwningPlayer().getName() and getOwnerDirect(), it may be necessary to use both or check the profile field, which this method should do. This method must be implemented with the following defined order: getOwningPlayer and getProfilePlayer if necessary to check name, then getOwner to check name.
        Parameters:
        skullBlockState - the blockstate of the skull to check
        Returns:
        the owner name or null if none could be found.

      • setOwningPlayer

        boolean setOwningPlayer​(SkullMeta skullItemMeta,
                        OfflinePlayer op)
        Sets the player owning a skull
        Parameters:
        skullItemMeta - the ItemMeta of a skull
        op - the owning player
        Returns:
        whether the process succeeded

      • setOwningPlayer

        void setOwningPlayer​(Skull skullBlockState,
                     OfflinePlayer op)
        Sets the player owning a skull
        Parameters:
        skullBlockState - the BlockState of a skull
        op - the owning player

      • setOwner

        boolean setOwner​(SkullMeta skullItemMeta,
                 String owner)
        Sets the owner username of a skull
        Parameters:
        skullItemMeta - the ItemMeta of a skull
        owner - the owner username to set
        Returns:
        whether the process succeeded

      • setOwner

        boolean setOwner​(Skull skullBlockState,
                 String owner)
        Sets the owner username of a skull
        Parameters:
        skullBlockState - the BlockState of a skull
        owner - the owner username to set
        Returns:
        whether the process succeeded

      • getItemInMainHand

        ItemStack getItemInMainHand​(Player p)
        Gets the itemstack in the [main] hand of a player
        Parameters:
        p - the player to check
        Returns:
        The ItemStack if found, or null

      • setItemInMainHand

        void setItemInMainHand​(Player p,
                       ItemStack s)
        Sets the itemstack in the [main] hand of a player
        Parameters:
        p - the player to change
        s - the itemstack to set in their hand

      • getSkullDetails

        SkullDetails getSkullDetails​(SkullType type)
        Gets a class describing implementation-specific details about a vanilla skull type
        Parameters:
        type - the type of vanilla head or skull to check
        Returns:
        the object containing details about the skull type
        See Also:
        SkullType

      • getKeepInventory

        boolean getKeepInventory​(World world)
        Checks whether the keepinventory gamerule is enabled for a given world
        Parameters:
        world - the world to check in
        Returns:
        whether the gamerule is enabled

      • getSkullType

        SkullType getSkullType​(ItemStack s)
        Gets the vanilla skulltype best associated with the ItemStack provided. Note: this method does not perform any username, UUID, or texture checks, so any skull that is not directly supported in the current server (such as a dragon head in 1.8) will return SkullType.PLAYER instead. It only determines what skulltype is associated with the vanilla types available.
        Parameters:
        s - The itemstack to check
        Returns:
        the skulltype associated with the object.

      • getSkullType

        SkullType getSkullType​(BlockState s)
        Gets the vanilla skulltype best associated with the BlockState provided. Note: this method does not perform any username, UUID, or texture checks, so any skull that is not directly supported in the current server (such as a dragon head in 1.8) will return SkullType.PLAYER instead. It only determines what skulltype is associated with the vanilla types available.
        Parameters:
        s - The blockstate to check
        Returns:
        the skulltype associated with the object.

      • isHead

        boolean isHead​(ItemStack s)
        Checks whether the itemstack corresponds a vanilla head or skull of some type.
        Parameters:
        s - the itemstack to check
        Returns:
        whether the object is a head

      • isHead

        boolean isHead​(BlockState s)
        Checks whether the blockstate corresponds a vanilla head or skull of some type.
        Parameters:
        s - the blockstate to check
        Returns:
        whether the object is a head

      • isPlayerhead

        boolean isPlayerhead​(ItemStack s)
        Checks whether the itemstack corresponds to a vanilla player-head type
        Parameters:
        s - the itemstack to check
        Returns:
        whether the object is a playerhead

      • isPlayerhead

        boolean isPlayerhead​(BlockState s)
        Checks whether the blockstate corresponds to a vanilla player-head type
        Parameters:
        s - the blockstate to check
        Returns:
        whether the object is a playerhead

      • isMobhead

        boolean isMobhead​(ItemStack s)
        Checks whether the itemstack corresponds to a vanilla head or skull and is not a player-head type
        Parameters:
        s - the itemstack to check
        Returns:
        whether the object is a mobhead

      • isMobhead

        boolean isMobhead​(BlockState s)
        Checks whether the blockstate corresponds to a vanilla head or skull and is not a player-head type
        Parameters:
        s - the blockstate to check
        Returns:
        whether the object is a mobhead

      • getCompatibleNameFromEntity

        String getCompatibleNameFromEntity​(Entity e)
        Gets a forward-portable name of an entity. This gets the name of the entity as it appears in the EntityType enum of newer bukkit versions, even if the mob is a variant in the current version. This value can be used to correspond entities to their heads.
        Parameters:
        e - the entity to check
        Returns:
        the portable name of the string.
        See Also:
        EntityType

      • getEntityTypeFromTypename

        EntityType getEntityTypeFromTypename​(String ename)
        Gets an entity type from the Typename of an entity. This exists because EntityType names can change between Spigot-API versions.
        Parameters:
        ename - the entity-type name requested.
        Returns:
        the corresponding entity-type, or null if it doesn't exist.

      • setProfile

        boolean setProfile​(ItemMeta headMeta,
                   UUID uuid,
                   String texture)
        Set a profile field in the supplied item meta using a UUID and Texture string
        Parameters:
        headMeta - the item meta to apply the profile on
        uuid - A UUID to be associated with this profile and texture
        texture - The Base64-encoded Texture-URL tags.
        Returns:
        True: the profile was successfully set. False: the profile could not be set.

      • setProfile

        boolean setProfile​(Skull headBlockState,
                   UUID uuid,
                   String texture)
        Set a profile field in the supplied block state using a UUID and Texture string
        Parameters:
        headBlockState - the block state to apply the profile on
        uuid - A UUID to be associated with this profile and texture
        texture - The Base64-encoded Texture-URL tags.
        Returns:
        True: the profile was successfully set. False: the profile could not be set.

      • getOfflinePlayerByName

        OfflinePlayer getOfflinePlayerByName​(String username)
        Gets a player by their username
        Parameters:
        username - the username of the player
        Returns:
        the offline-player

      • getItemInMainHand

        ItemStack getItemInMainHand​(LivingEntity p)
        Gets the item in the [main] hand of the entity. In older server versions this should just retrieve the hand item.
        Parameters:
        p - the living entity (mob or player)
        Returns:
        the ItemStack retrieved for the entity's hand.
        Since:
        5.0.0

      • getProfile

        @Deprecated
@Nullable
Object getProfile​(ItemMeta headMeta)
           throws IllegalStateException
        Deprecated.
        This method should be avoided entirely or used only for acceptable-failure situations because of server support limitations.
        Gets the Profile object associated with a head, if possible. The return type is offered as an Object to remove reliance on authlib. NOTE: depending on server implementation, the Profile is not guaranteed to be a GameProfile - you should not act on this object directly, but only get/set it. Providers that are not capable of retrieving this should throw an IllegalStateException.
        Parameters:
        headMeta - the meta of the head item
        Returns:
        the Profile object object for the head, or null.
        Throws:
        IllegalStateException - when the provider does not support GameProfiile access.
        Since:
        5.2.12

      • getProfile

        @Deprecated
@Nullable
Object getProfile​(Skull headBlockState)
           throws IllegalStateException
        Deprecated.
        This method should be avoided entirely or used only for acceptable-failure situations because of server support limitations.
        Gets the Profile object associated with a head, if possible. The return type is offered as an Object to remove reliance on authlib. NOTE: depending on server implementation, the Profile is not guaranteed to be a GameProfile - you should not act on this object directly, but only get/set it.
        Parameters:
        headBlockState - the blockstate of the head block
        Returns:
        the Profile object object for the head, or null.
        Throws:
        IllegalStateException - when the provider does not support GameProfiile access.
        Since:
        5.2.12

      • setProfile

        @Deprecated
boolean setProfile​(ItemMeta headMeta,
                   Object profile)
            throws IllegalStateException,
                   IllegalArgumentException
        Deprecated.
        This method should be avoided entirely or used only for acceptable-failure situations because of server support limitations.
        Sets the Profile object on a head, if possible. Providers that are not capable of retrieving this should throw an IllegalStateException. IllegalArgumentException should be thrown if the input is not null and also not a Profile object type. NOTE: depending on server implementation, the Profile is not guaranteed to be a GameProfile - you should not act on this object directly, but only get/set it.
        Parameters:
        headMeta - the meta of the head item
        profile - the Profile object object to set in the head
        Returns:
        whether setting the profile field succeeded
        Throws:
        IllegalStateException - when the provider does not support GameProfiile access.
        IllegalArgumentException - when the the input profile was not am acceptable Profile object type and not null
        Since:
        5.2.12

      • setProfile

        @Deprecated
boolean setProfile​(Skull headBlockState,
                   Object profile)
            throws IllegalStateException,
                   IllegalArgumentException
        Deprecated.
        This method should be avoided entirely or used only for acceptable-failure situations because of server support limitations.
        Sets the Profile object on a head, if possible. Providers that are not capable of retrieving this should throw an IllegalStateException. IllegalArgumentException should be thrown if the input is not null and also not a Profile object type. NOTE: depending on server implementation, the Profile is not guaranteed to be a GameProfile - you should not act on this object directly, but only get/set it.
        Parameters:
        headBlockState - the blockstate of the head block
        profile - the Profile object object to set in the head
        Returns:
        whether setting the profile field succeeded
        Throws:
        IllegalStateException - when the provider does not support GameProfiile access.
        IllegalArgumentException - when the the input profile was not am acceptable Profile object type and not null
        Since:
        5.2.12

      • getOptionalProfile

        @Deprecated
Optional<Object> getOptionalProfile​(ItemMeta skullMeta)
        Deprecated.
        Use CompatibleProfile or profile methods instead. This API may be removed in the future.
        Gets the Optional Profile object for a head. This method must return an Optional object which 'is present' if the profile has a retrievable value (including null). Otherwise, the Optional must be 'empty'.
        Parameters:
        skullMeta - the meta for a head item
        Returns:
        The optional profile object

      • getOptionalProfile

        @Deprecated
Optional<Object> getOptionalProfile​(Skull skullState)
        Deprecated.
        Use CompatibleProfile or profile methods instead. This API may be removed in the future.
        Gets the Optional Profile object for a head. This method must return an Optional object which 'is present' if the profile has a retrievable value (including null). Otherwise, the Optional must be 'empty'. NOTE: depending on server implementation, the Profile is not guaranteed to be a GameProfile or even present - you should not act on this object directly, but only get/set it.
        Parameters:
        skullState - the blockstate for a head item
        Returns:
        The optional profile object

      • setOptionalProfile

        @Deprecated
boolean setOptionalProfile​(Skull skullState,
                           Optional<Object> profile)
        Deprecated.
        Use CompatibleProfile or profile methods instead. This API may be removed in the future.
        Sets the Optional Profile object for a head. If the Optional value is 'empty' (not present), then nothing happens. If the Optional value is present, then it is set (even if it is null). NOTE: depending on server implementation, the Profile is not guaranteed to be a GameProfile or even present - you should not act on this object directly, but only get/set it.
        Parameters:
        skullState - the blockstate for a head item
        profile - the Optional profile object to set
        Returns:
        whether setting the profile succeeded. (nothing happening is considered failure).

      • setOptionalProfile

        @Deprecated
boolean setOptionalProfile​(ItemMeta skullMeta,
                           Optional<Object> profile)
        Deprecated.
        Use CompatibleProfile or profile methods instead. This API may be removed in the future.
        Sets the Optional Profile object for a head. If the Optional value is 'empty' (not present), then nothing happens. If the Optional value is present, then it is set (even if it is null). NOTE: depending on server implementation, the Profile is not guaranteed to be a GameProfile or even present - you should not act on this object directly, but only get/set it.
        Parameters:
        skullMeta - the meta for a head item
        profile - the Optional profile object to set
        Returns:
        whether setting the profile succeeded. (nothing happening is considered failure).

      • setCompatibleProfile

        boolean setCompatibleProfile​(Object skull,
                             CompatibleProfile profile)
                      throws IllegalArgumentException
        Sets a profile on a block or item. If the skull parameter is not the proper type, an except may be thrown.
        Parameters:
        skull - an object of type Skull (BlockState) or SkullMeta
        profile - the compatible profile object, or specific implementation child object.
        Returns:
        whether setting a profile succeeded.
        Throws:
        IllegalArgumentException - if the skull parameter was not the specified type
        Since:
        5.2.13-SNAPSHOT

      • getCompatibleProfile

        CompatibleProfile getCompatibleProfile​(Object skull)
                                throws IllegalArgumentException
        Gets a profile on a block or item. If the skull parameter is not
        Parameters:
        skull - an object of type Skull (BlockState) or SkullMeta
        Returns:
        the profile from the head if it exists, or null
        Throws:
        IllegalArgumentException - if the skull parameter was not the specified type
        Since:
        5.2.13-SNAPSHOT

      • createCompatibleProfile

        CompatibleProfile createCompatibleProfile​(@Nullable
                                          String name,
                                          @Nullable
                                          UUID id,
                                          @Nullable
                                          String texture)
                                   throws IllegalArgumentException
        Create a compatible profile object with the provided parameters. Note: name and id cannot both be null, only one can be null.
        Parameters:
        name - the owner username of the head (this should not be a custom name - use null instead)
        id - A UUID to be associated with this profile and texture (this may be a custom/unique value that you manage - you are strongly recommended to choose a static but randomly-generated ID)
        texture - The Base64-encoded Texture-URL tags. (this may be null to set no texture)
        Returns:
        the CompatibleProfile object
        Throws:
        IllegalArgumentException - if both the name and id are null.
        Since:
        5.2.13-SNAPSHOT

      • getCompatibleHeadItem

        @NotNull
ItemStack getCompatibleHeadItem​(@NotNull
                                CompatibleSkullMaterial material,
                                int amount)
        Gets the head used as a base for a displaying a given vanilla skull type. Note: if the particular skull-type is not supported in your server version, this will create a Player-type head for you to use for skinning/placeholding. If you want more control over head happens in these cases, consider using CompatibleSkullMaterial directly.
        Parameters:
        material - the supported compatible skull material/type
        amount - amount of items to create in the stack
        Returns:
        an ItemStack of the head
        Since:
        5.2.13-SNAPSHOT

      • isCustomHead

        boolean isCustomHead​(String username,
                     UUID id)
        Determine if a head profile is a custom head or not, created by a plugin or for decoration. This is a best-guess determination based on whether a username is set and possibly other details. You should check head information further in addition to this step (eg: check plugin-reserved UUIDs and names)
        Parameters:
        username - username associated with the head
        id - the UUID associated with the head
        Returns:
        whether it is assumed to be a custom head.
        Throws:
        IllegalArgumentException - if profile is null
        Since:
        5.2.14-SNAPSHOT

      • isCustomHead

        boolean isCustomHead​(CompatibleProfile profile)
        Determine if a head profile is a custom head or not, created by a plugin or for decoration. This is a best-guess determination based on whether a username is set and possibly other details. You should check head information further in addition to this step (eg: check plugin-reserved UUIDs and names)
        Parameters:
        profile - the profile information for the head
        Returns:
        whether it is assumed to be a custom head.
        Throws:
        IllegalArgumentException - if profile is null
        Since:
        5.2.14-SNAPSHOT

      • isCustomHead

        boolean isCustomHead​(Object skull)
        Determine if a head profile is a custom head or not, created by a plugin or for decoration. This is a best-guess determination based on whether a username is set and possibly other details. You should check head information further in addition to this step (eg: check plugin-reserved UUIDs and names)
        Parameters:
        skull - the profile information for the head
        Returns:
        whether it is assumed to be a custom head.
        Throws:
        IllegalArgumentException - if profile is null or not a skull type (SkullMeta, Skull block)
        Since:
        5.2.14-SNAPSHOT

      • clearProfile

        boolean clearProfile​(Object skull)
              throws IllegalArgumentException
        Clears internal profile information from a skull.
        Parameters:
        skull - a Skull blockstate or SkullMeta object to clear the profile from
        Returns:
        false if clearing the profile failed or was unsupported, otherwise true.
        Throws:
        IllegalArgumentException
        Since:
        5.2.14-SNAPSHOT

      • getKillerEntity

        LivingEntity getKillerEntity​(EntityDeathEvent event,
                             boolean considermobkillers,
                             boolean considertameowners)
        Attempt to determine the entity/player ultimately responsible for a death.
        Parameters:
        event - the entity death event
        considermobkillers - whether to search into non-player killers (projectiles, mobs). If this is false, the behavior must be identical to entity.getKiller()
        considertameowners - whether to include the owner of tamed mobs in the search (requires considermobkillers)
        Returns:
        the entity ultimately responsible for the death, as well as we could tell.
        Since:
        5.2.14-SNAPSHOT

      • supportsEntityTagType

        boolean supportsEntityTagType​(boolean persistent)
        Checks whether the compatibility provider supports entity tags of the provided type
        Parameters:
        persistent - whether the tag should be persistent (saved through restarts).
        Returns:
        whether the tags were supported

      • setEntityTag

        boolean setEntityTag​(Entity entity,
                     Plugin plugin,
                     String key,
                     String value,
                     boolean persistent)
        Sets a custom tag on the entity. This should only be used for information-tracking purposes (such as spawn-cause). Not all versions may support setting persistent tags - you must check the result. Tag support will be different between versions - a tag may not be detected in a different server version.
        Parameters:
        entity - the entity to set the tag on.
        plugin - the plugin requesting the tag to be set.
        key - the key or name of the tag to set
        value - the value of the tag to set, or null to remove it.
        persistent - whether the tag should be persistent (saved through restarts).
        Returns:
        whether the requested tag could be set. Usually this will fail if Persistence is not supported.
        Since:
        5.2.15-SNAPSHOT

      • getEntityTag

        @Nullable
String getEntityTag​(Entity entity,
                    Plugin plugin,
                    String key,
                    boolean persistent)
        Retrieves a custom tag on an entity.
        Parameters:
        entity - the entity containing the tag
        plugin - the plugin which set the tag
        key - the key or name of the tag
        persistent - whether the tag was set as persistent (saved through restarts).
        Returns:
        the tag's value, or null if it is not present
        Since:
        5.2.15-SNAPSHOT