EffectiveSpigot/ru.hukm.effectiveSpigot.minecraft.utils/EffectiveDataContainerUtils

EffectiveDataContainerUtils

Helpers for reading and writing Bukkit PersistentDataContainer (PDC) data on items, entities and other PersistentDataHolders.

Beyond thin typed get/set wrappers, it adds conveniences the vanilla API lacks:

reified get/setContainerValue<T> that infer the PersistentDataType from T;
UUID / entity storage packed into LONG_ARRAY keys (single and lists);
Base64 serialization of arbitrary Serializable/Bukkit objects (and item lists);
nested containers, and structured Location storage.

Every getter returns null (rather than throwing) when the key is absent or the holder has no meta. Note: mutating an ItemStack's PDC goes through its itemMeta, so the set*(ItemStack, …) overloads return the updated stack — use the returned value.

Functions

base64Deserialize

fun <Z> base64Deserialize(base64: String?, clazz: Class<Z?>): Z?

Deserializes a Base64 string produced by base64Serialize back to clazz, or null on failure.

base64GetContainerValue

fun <Z> base64GetContainerValue(item: ItemStack, key: NamespacedKey, clazz: Class<Z?>): Z?

Reads a Base64-serialized object of type clazz from the item's string value at key, or null.

fun <Z> base64GetContainerValue(holder: PersistentDataHolder, key: NamespacedKey, clazz: Class<Z?>): Z?

Reads a Base64-serialized object of type clazz from the holder's string value at key, or null.

base64Serialize

fun base64Serialize(object: Any?): String?

Serializes any Bukkit/Serializable object to a URL-safe Base64 string, or null on failure.

base64SetContainerValue

fun <Z> base64SetContainerValue(item: ItemStack, key: NamespacedKey, value: Z?): ItemStack

Serializes value to Base64 and stores it as the item's string value at key. Returns the stack.

fun <Z> base64SetContainerValue(holder: PersistentDataHolder, key: NamespacedKey, value: Z?)

Serializes value to Base64 and stores it as the holder's string value at key.

getContainer

fun <T> getContainer(item: ItemStack, key: NamespacedKey, block: (PersistentDataContainer) -> T): T?

Reads the nested container at key on an item and maps it via block, or null if absent.

fun <T> getContainer(holder: PersistentDataHolder, key: NamespacedKey, block: (PersistentDataContainer) -> T): T?

Reads the nested container at key and maps it via block, or null if absent.

getContainerValue

inline fun <T : Any> getContainerValue(item: ItemStack, key: NamespacedKey): T?

Reads key from the item's PDC, inferring the PersistentDataType from T.

inline fun <T : Any> getContainerValue(container: PersistentDataContainer, key: NamespacedKey): T?

Reads key from a PersistentDataContainer, inferring the type from T.

inline fun <T : Any> getContainerValue(holder: PersistentDataHolder, key: NamespacedKey): T?

Reads key from the holder's PDC, inferring the type from T.

fun <Z : Any, T : Any> getContainerValue(item: ItemStack, key: NamespacedKey, type: PersistentDataType<T, Z>): Z?

Reads key of the given type from the item's PDC, or null if absent/no meta.

fun <Z : Any, T : Any> getContainerValue(container: PersistentDataContainer, key: NamespacedKey, type: PersistentDataType<T, Z>): Z?

Reads key of the given type directly from a PersistentDataContainer, or null.

fun <Z : Any, T : Any> getContainerValue(holder: PersistentDataHolder, key: NamespacedKey, type: PersistentDataType<T, Z>): Z?

Reads key of the given type from the holder's PDC (entity, block state, …), or null.

getEntitiesFromLongArray

fun getEntitiesFromLongArray(holder: PersistentDataHolder, key: NamespacedKey): List<Entity?>?

Resolves entities from UUIDs packed under key; list entries are null for offline entities.

getEntityByUUIDValue

fun getEntityByUUIDValue(holder: PersistentDataHolder, key: NamespacedKey): Entity?

Resolves an entity stored as its UUID string under key, or null if not stored/offline.

getEntityFromLongArray

fun getEntityFromLongArray(holder: PersistentDataHolder, key: NamespacedKey): Entity?

Resolves a single entity from a UUID packed under key, or null if not stored/offline.

getItems

fun getItems(item: ItemStack, key: NamespacedKey): List<ItemStack?>?

Reads a list of items stored under key on an item (entries may be null), or null if absent.

fun getItems(holder: PersistentDataHolder, key: NamespacedKey): List<ItemStack?>?

Reads a list of items stored under key (entries may be null), or null if absent.

getLocation

fun getLocation(item: ItemStack, key: NamespacedKey): Location?

Reads a Location stored under key on an item, or null if absent/world unloaded.

fun getLocation(holder: PersistentDataHolder, key: NamespacedKey): Location?

Reads a Location stored under key, or null if absent or its world is unloaded.

getUUIDFromLongArray

fun getUUIDFromLongArray(holder: PersistentDataHolder, key: NamespacedKey): UUID?

Reads a single UUID packed as a 2-element LONG_ARRAY under key, or null.

getUUIDsFromLongArray

fun getUUIDsFromLongArray(holder: PersistentDataHolder, key: NamespacedKey): List<UUID>?

Reads a list of UUIDs packed as pairs of longs under key, or null.

hasContainerValue

fun <Z : Any, T : Any> hasContainerValue(item: ItemStack, key: NamespacedKey, type: PersistentDataType<T, Z>): Boolean

Whether the item's PDC has key of the given type.

fun <Z : Any, T : Any> hasContainerValue(holder: PersistentDataHolder, key: NamespacedKey, type: PersistentDataType<T, Z>): Boolean

Whether the holder's PDC has key of the given type.

setContainer

fun setContainer(item: ItemStack, key: NamespacedKey, block: (PersistentDataContainer) -> Unit): ItemStack

setContainer for items: opens/creates a nested container at key, mutates it, writes back. Returns the stack.

fun setContainer(holder: PersistentDataHolder, key: NamespacedKey, block: (PersistentDataContainer) -> Unit)

Opens (or creates) a nested container at key, lets block mutate it, then writes it back. The building block for structured storage like setLocation.

setContainerValue

inline fun <T : Any> setContainerValue(item: ItemStack, key: NamespacedKey, value: T?): ItemStack

Writes value under key on the item's PDC (type inferred from T); null removes the key.

inline fun <T : Any> setContainerValue(container: PersistentDataContainer, key: NamespacedKey, value: T?)

Writes value under key on a PersistentDataContainer (type inferred from T); null removes it.

inline fun <T : Any> setContainerValue(holder: PersistentDataHolder, key: NamespacedKey, value: T?)

Writes value under key on the holder's PDC (type inferred from T); null removes the key.

fun <Z : Any, T : Any> setContainerValue(item: ItemStack, key: NamespacedKey, type: PersistentDataType<T, Z>, value: Z?): ItemStack

Writes value of the given type under key on the item's PDC; null removes the key.

fun <Z : Any, T : Any> setContainerValue(container: PersistentDataContainer, key: NamespacedKey, type: PersistentDataType<T, Z>, value: Z?)

Writes value of the given type under key on a PersistentDataContainer; null removes it.

fun <Z : Any, T : Any> setContainerValue(holder: PersistentDataHolder, key: NamespacedKey, type: PersistentDataType<T, Z>, value: Z?)

Writes value of the given type under key on the holder's PDC; null removes the key.

setItems

fun setItems(item: ItemStack, key: NamespacedKey, items: List<ItemStack?>?): ItemStack

Stores a list of items (Base64) under key on an item; null removes it. Returns the stack.

fun setItems(holder: PersistentDataHolder, key: NamespacedKey, items: List<ItemStack?>?)

Stores a list of items (Base64) under key; null removes the key.

setLocation

fun setLocation(item: ItemStack, key: NamespacedKey, location: Location?): ItemStack

Stores a Location as a nested container under key on an item; null removes it. Returns the stack.

fun setLocation(holder: PersistentDataHolder, key: NamespacedKey, location: Location?)

Stores a Location (world, x/y/z, yaw/pitch) as a nested container under key; null removes it.

setUUIDsToLongArray

fun setUUIDsToLongArray(holder: PersistentDataHolder, key: NamespacedKey, uuids: List<UUID>)

Stores a list of uuids as consecutive long pairs under key.

setUUIDToLongArray

fun setUUIDToLongArray(holder: PersistentDataHolder, key: NamespacedKey, uuid: UUID)

Stores a single uuid as a 2-element LONG_ARRAY under key.