Package com.jeff_media.customblockdata

Class CustomBlockData

java.lang.Object
com.jeff_media.customblockdata.CustomBlockData
All Implemented Interfaces:
PersistentDataContainer
public class CustomBlockData extends Object implements 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 Details

    • CustomBlockData

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

    • CustomBlockData

      @Deprecated public CustomBlockData(@NotNull Block block, @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(Block block, Plugin plugin)
      Get if the given Block has any CustomBockData associated with it

    • isProtected

      public static boolean isProtected(Block block, 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(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 Set<Block> getBlocksWithCustomData(Plugin plugin, 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 Set<Block> getBlocksWithCustomData(String namespace, 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 PersistentDataType<?,?> getDataType(PersistentDataContainer pdc, 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 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(Block block, 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 NamespacedKey namespacedKey, @NotNull PersistentDataType<T,Z> persistentDataType, @NotNull Z z)
      Specified by:
      set in interface PersistentDataContainer

    • has

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

    • has

      public boolean has(@NotNull NamespacedKey namespacedKey)
      Specified by:
      has in interface PersistentDataContainer

    • get

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

    • getOrDefault

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

    • getKeys

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

    • remove

      public void remove(@NotNull NamespacedKey namespacedKey)
      Specified by:
      remove in interface PersistentDataContainer

    • isEmpty

      public boolean isEmpty()
      Specified by:
      isEmpty in interface PersistentDataContainer

    • getAdapterContext

      @NotNull public PersistentDataAdapterContext getAdapterContext()
      Specified by:
      getAdapterContext in interface PersistentDataContainer

    • serializeToBytes

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

    • readFromBytes

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

    • readFromBytes

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

    • getDataType

      public PersistentDataType<?,?> getDataType(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