Package com.jeff_media.customblockdata

Class CustomBlockData

java.lang.Object
com.jeff_media.customblockdata.CustomBlockData
All Implemented Interfaces:
org.bukkit.persistence.PersistentDataContainer
public class CustomBlockData extends Object implements org.bukkit.persistence.PersistentDataContainer
Represents a PersistentDataContainer for a specific Block. Also provides some static utility methods that can be used on every PersistentDataContainer.

By default, and for backward compatibility reasons, data stored inside blocks is independent of the underlying block. That means: if you store some data inside a dirt block, and that block is now pushed by a piston, then the information will still reside in the old block's location. You can of course also make CustomBockData automatically take care of those situations, so that CustomBlockData will always be updated on certain Bukkit Events like BlockBreakEvent, EntityExplodeEvent, etc. For more information about this please see registerListener(Plugin).

  • Constructor Summary

    Constructors
    Constructor
    Description
    CustomBlockData(@NotNull org.bukkit.block.Block block, @NotNull String namespace)
    Deprecated.
    Use CustomBlockData(Block, Plugin) instead.
    CustomBlockData(@NotNull org.bukkit.block.Block block, @NotNull org.bukkit.plugin.Plugin plugin)
    Gets the PersistentDataContainer associated with the given block and plugin

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clear()
    Removes all CustomBlockData and disables the protection status (setProtected(boolean)
    void
    copyTo(org.bukkit.block.Block block, org.bukkit.plugin.Plugin plugin)
    Copies all data to another block.
    <T, Z> Z
    get(@NotNull org.bukkit.NamespacedKey namespacedKey, @NotNull org.bukkit.persistence.PersistentDataType<T,Z> persistentDataType)
     
    @NotNull org.bukkit.persistence.PersistentDataAdapterContext
    getAdapterContext()
     
    @Nullable org.bukkit.block.Block
    getBlock()
    Gets the Block associated with this CustomBlockData, or null if the world is no longer loaded.
    static @NotNull Set<org.bukkit.block.Block>
    getBlocksWithCustomData(String namespace, org.bukkit.Chunk chunk)
    Returns a Set of all blocks in this Chunk containing Custom Block Data created by the given plugin
    static @NotNull Set<org.bukkit.block.Block>
    getBlocksWithCustomData(org.bukkit.plugin.Plugin plugin, org.bukkit.Chunk chunk)
    Returns a Set of all blocks in this chunk containing Custom Block Data created by the given plugin
    org.bukkit.persistence.PersistentDataType<?,?>
    getDataType(org.bukkit.NamespacedKey key)
    Gets the proper primitive PersistentDataType for the given NamespacedKey
    static org.bukkit.persistence.PersistentDataType<?,?>
    getDataType(org.bukkit.persistence.PersistentDataContainer pdc, org.bukkit.NamespacedKey key)
    Gets the proper primitive PersistentDataType for the given NamespacedKey in the given PersistentDataContainer
    @NotNull Set<org.bukkit.NamespacedKey>
    getKeys()
     
    <T, Z> Z
    getOrDefault(@NotNull org.bukkit.NamespacedKey namespacedKey, @NotNull org.bukkit.persistence.PersistentDataType<T,Z> persistentDataType, Z z)
     
    boolean
    has(@NotNull org.bukkit.NamespacedKey namespacedKey)
     
    <T, Z> boolean
    has(@NotNull org.bukkit.NamespacedKey namespacedKey, @NotNull org.bukkit.persistence.PersistentDataType<T,Z> persistentDataType)
     
    static boolean
    hasCustomBlockData(org.bukkit.block.Block block, org.bukkit.plugin.Plugin plugin)
    Get if the given Block has any CustomBockData associated with it
    boolean
    isEmpty()
     
    boolean
    isProtected()
    Gets whether this CustomBlockData is protected.
    static boolean
    isProtected(org.bukkit.block.Block block, org.bukkit.plugin.Plugin plugin)
    Get if the given Block's CustomBlockData is protected.
    void
    readFromBytes(byte[] bytes)
    Deprecated.
    Paper-only
    void
    readFromBytes(byte[] bytes, boolean clear)
    Deprecated.
    Paper-only
    static void
    registerListener(org.bukkit.plugin.Plugin plugin)
    Starts to listen and manage block-related events such as BlockBreakEvent.
    void
    remove(@NotNull org.bukkit.NamespacedKey namespacedKey)
     
    @org.jetbrains.annotations.NotNull byte[]
    serializeToBytes()
    Deprecated.
    Paper-only
    <T, Z> void
    set(@NotNull org.bukkit.NamespacedKey namespacedKey, @NotNull org.bukkit.persistence.PersistentDataType<T,Z> persistentDataType, Z z)
     
    void
    setProtected(boolean isProtected)
    Sets whether this CustomBlockData is protected.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • CustomBlockData

      public CustomBlockData(@NotNull @NotNull org.bukkit.block.Block block, @NotNull @NotNull org.bukkit.plugin.Plugin plugin)
      Gets the PersistentDataContainer associated with the given block and plugin
      Parameters:
      block - Block
      plugin - Plugin

    • CustomBlockData

      @Deprecated public CustomBlockData(@NotNull @NotNull org.bukkit.block.Block block, @NotNull @NotNull String namespace)
      Deprecated.
      Use CustomBlockData(Block, Plugin) instead.
      Gets the PersistentDataContainer associated with the given block and plugin
      Parameters:
      block - Block
      namespace - Namespace

  • Method Details

    • hasCustomBlockData

      public static boolean hasCustomBlockData(org.bukkit.block.Block block, org.bukkit.plugin.Plugin plugin)
      Get if the given Block has any CustomBockData associated with it

    • isProtected

      public static boolean isProtected(org.bukkit.block.Block block, org.bukkit.plugin.Plugin plugin)
      Get if the given Block's CustomBlockData is protected. Protected CustomBlockData will not be changed by any Bukkit Events
      Returns:
      true if the Block's CustomBlockData is protected, false if it doesn't have any CustomBlockData or it's not protected
      See Also:

    • registerListener

      public static void registerListener(org.bukkit.plugin.Plugin plugin)
      Starts to listen and manage block-related events such as BlockBreakEvent. By default, CustomBlockData is "stateless". That means: when you add data to a block, and now a player breaks the block, the data will still reside at the original block location. This is to ensure that you always have full control about what data is saved at which location.

      If you do not want to handle this yourself, you can instead let CustomBlockData handle those events by calling this method once. It will then listen to the common events itself, and automatically remove/update CustomBlockData.

      Block changes made using the Bukkit API (e.g. Block.setType(Material)) or using a plugin like WorldEdit will not be registered by this (but pull requests are welcome, of course)

      For example, when you call this method in onEnable, CustomBlockData will now get automatically removed from a block when a player breaks this block. It will additionally call custom events like CustomBlockDataRemoveEvent. Those events implement Cancellable. If one of the CustomBlockData events is cancelled, it will not alter any CustomBlockData.

      Parameters:
      plugin - Your plugin's instance

    • getBlocksWithCustomData

      @NotNull public static @NotNull Set<org.bukkit.block.Block> getBlocksWithCustomData(org.bukkit.plugin.Plugin plugin, org.bukkit.Chunk chunk)
      Returns a Set of all blocks in this chunk containing Custom Block Data created by the given plugin
      Parameters:
      plugin - Plugin
      chunk - Chunk
      Returns:
      A Set containing all blocks in this chunk containing Custom Block Data created by the given plugin

    • getBlocksWithCustomData

      @NotNull public static @NotNull Set<org.bukkit.block.Block> getBlocksWithCustomData(String namespace, org.bukkit.Chunk chunk)
      Returns a Set of all blocks in this Chunk containing Custom Block Data created by the given plugin
      Parameters:
      namespace - Namespace
      chunk - Chunk
      Returns:
      A Set containing all blocks in this chunk containing Custom Block Data created by the given plugin

    • getDataType

      public static org.bukkit.persistence.PersistentDataType<?,?> getDataType(org.bukkit.persistence.PersistentDataContainer pdc, org.bukkit.NamespacedKey key)
      Gets the proper primitive PersistentDataType for the given NamespacedKey in the given PersistentDataContainer
      Returns:
      The primitive PersistentDataType for the given key, or null if the key doesn't exist

    • getBlock

      @Nullable public @Nullable org.bukkit.block.Block getBlock()
      Gets the Block associated with this CustomBlockData, or null if the world is no longer loaded.

    • isProtected

      public boolean isProtected()
      Gets whether this CustomBlockData is protected. Protected CustomBlockData will not be changed by any Bukkit Events
      See Also:

    • setProtected

      public void setProtected(boolean isProtected)
      Sets whether this CustomBlockData is protected. Protected CustomBlockData will not be changed by any Bukkit Events
      See Also:

    • clear

      public void clear()
      Removes all CustomBlockData and disables the protection status (setProtected(boolean)

    • copyTo

      public void copyTo(org.bukkit.block.Block block, org.bukkit.plugin.Plugin plugin)
      Copies all data to another block. Data already present in the destination block will keep intact, unless it gets overwritten by identically named keys. Data in the source block won't be changed.

    • set

      public <T, Z> void set(@NotNull @NotNull org.bukkit.NamespacedKey namespacedKey, @NotNull @NotNull org.bukkit.persistence.PersistentDataType<T,Z> persistentDataType, @NotNull Z z)
      Specified by:
      set in interface org.bukkit.persistence.PersistentDataContainer

    • has

      public <T, Z> boolean has(@NotNull @NotNull org.bukkit.NamespacedKey namespacedKey, @NotNull @NotNull org.bukkit.persistence.PersistentDataType<T,Z> persistentDataType)
      Specified by:
      has in interface org.bukkit.persistence.PersistentDataContainer

    • has

      public boolean has(@NotNull @NotNull org.bukkit.NamespacedKey namespacedKey)
      Specified by:
      has in interface org.bukkit.persistence.PersistentDataContainer

    • get

      @Nullable public <T, Z> Z get(@NotNull @NotNull org.bukkit.NamespacedKey namespacedKey, @NotNull @NotNull org.bukkit.persistence.PersistentDataType<T,Z> persistentDataType)
      Specified by:
      get in interface org.bukkit.persistence.PersistentDataContainer

    • getOrDefault

      @NotNull public <T, Z> Z getOrDefault(@NotNull @NotNull org.bukkit.NamespacedKey namespacedKey, @NotNull @NotNull org.bukkit.persistence.PersistentDataType<T,Z> persistentDataType, @NotNull Z z)
      Specified by:
      getOrDefault in interface org.bukkit.persistence.PersistentDataContainer

    • getKeys

      @NotNull public @NotNull Set<org.bukkit.NamespacedKey> getKeys()
      Specified by:
      getKeys in interface org.bukkit.persistence.PersistentDataContainer

    • remove

      public void remove(@NotNull @NotNull org.bukkit.NamespacedKey namespacedKey)
      Specified by:
      remove in interface org.bukkit.persistence.PersistentDataContainer

    • isEmpty

      public boolean isEmpty()
      Specified by:
      isEmpty in interface org.bukkit.persistence.PersistentDataContainer

    • getAdapterContext

      @NotNull public @NotNull org.bukkit.persistence.PersistentDataAdapterContext getAdapterContext()
      Specified by:
      getAdapterContext in interface org.bukkit.persistence.PersistentDataContainer

    • serializeToBytes

      @NotNull @Deprecated public @org.jetbrains.annotations.NotNull byte[] serializeToBytes() throws IOException
      Deprecated.
      Paper-only
      Specified by:
      serializeToBytes in interface org.bukkit.persistence.PersistentDataContainer
      Throws:
      IOException
      See Also:
      • PersistentDataContainer.serializeToBytes()

    • readFromBytes

      @Deprecated public void readFromBytes(byte[] bytes, boolean clear) throws IOException
      Deprecated.
      Paper-only
      Specified by:
      readFromBytes in interface org.bukkit.persistence.PersistentDataContainer
      Throws:
      IOException
      See Also:
      • ()

    • readFromBytes

      @Deprecated public void readFromBytes(byte[] bytes) throws IOException
      Deprecated.
      Paper-only
      Specified by:
      readFromBytes in interface org.bukkit.persistence.PersistentDataContainer
      Throws:
      IOException
      See Also:
      • ()

    • getDataType

      public org.bukkit.persistence.PersistentDataType<?,?> getDataType(org.bukkit.NamespacedKey key)
      Gets the proper primitive PersistentDataType for the given NamespacedKey
      Returns:
      The primitive PersistentDataType for the given key, or null if the key doesn't exist