Package valorless.havenbags.api

Class HavenBagsAPI

java.lang.Object
valorless.havenbags.api.HavenBagsAPI
public class HavenBagsAPI extends Object
Public API for interacting with HavenBags. Provides helpers to inspect items, fetch and mutate bag data, manage ethereal bags, and create tokens.

I also threw in a bunch of random methods.
Have fun!

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    HavenBagsAPI.GUI
    GUI-related utilities for HavenBags.

  • Constructor Summary

    Constructors
    Constructor
    Description
    HavenBagsAPI()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static boolean
    bagExists(String uuid)
    Checks whether a bag exists in storage.
    static org.bukkit.entity.Player
    bagOpenBy(String uuid)
    Gets the player who has the bag open.
    static int
    bagSlotsEmpty(org.bukkit.inventory.ItemStack bag)
    Counts the number of empty slots in the specified bag item.
    static String
    bagState(org.bukkit.inventory.ItemStack item)
    Retrieves the current state of the bag.
    static boolean
    blacklistAsWhitelist()
    Checks if the global configuration is set to treat the blacklist as a whitelist.
    static boolean
    blacklistAsWhitelist(Data bagData)
    Checks if the specified bag's configuration is set to treat its blacklist as a whitelist.
    static boolean
    canCarry(org.bukkit.inventory.ItemStack item, org.bukkit.inventory.ItemStack bag)
    Checks if the specified item can be carried in the given bag, considering weight limits.
    static boolean
    canCarryMoreBags(org.bukkit.entity.Player player)
    Checks if the player can carry more bags based on configured limits.
    static String
    capacityTexture(org.bukkit.inventory.ItemStack bag)
    Determines the appropriate texture for a bag based on its used capacity.
    static String
    convertUrlToBase64(String url)
    Converts a texture URL to a Base64-encoded string.
    static Data
    createBag(BagCreationObject creationObject)
    Creates and persists a new bag from the provided creation descriptor.
    static Data
    createBag(Data bagData)
    Creates and persists a new bag from the provided Data object.
    static org.bukkit.inventory.ItemStack
    createEffectToken(String value)
    Creates an effect token for the given effect identifier.
    static boolean
    createEtherealBag(String bagId, org.bukkit.entity.Player player, int size)
    Creates an ethereal bag entry for a player.
    static org.bukkit.inventory.ItemStack
    createToken(String value, TokenType type)
    Creates a skin token ItemStack for the given value and type.
    static org.bukkit.inventory.ItemStack
    createUnusedBagItem(int size, boolean binding)
    Creates an unused bag ItemStack with specified size and binding status.
    static org.bukkit.inventory.ItemStack
    creteHeadFromBase64(String base64)
    Creates a player head ItemStack with a custom texture from a Base64 string.
    static boolean
    deleteBag(String uuid)
    Deletes a bag by UUID.
    static String
    extractUrlFromBase64(String base64)
    Extracts the URL from a Base64-encoded texture string.
    static void
    forceCloseAllBags()
    Forces the closure of all open bags for all players.
    static org.bukkit.inventory.ItemStack
    generateBagItem(Data bagData)
    Generates a bag item from the provided Data.
    static Data
    getBag(String uuid)
    Fetches Data for a bag by UUID.
    static Data
    getBagData(org.bukkit.inventory.ItemStack item)
    Resolves the live Data object for the given bag item.
    static String
    getBagOwner(String uuid)
    Gets the owner UUID of a bag.
    static int
    getBagSlotsInInventory(org.bukkit.entity.Player player)
    Calculates the total number of bag slots in a player's inventory.
    static List<Data>
    getBagsOnPlayer(org.bukkit.entity.Player player)
    Lists all bag Data instances present in a player's inventory.
    static String
    getBagUUID(org.bukkit.inventory.ItemStack item)
    Gets the UUID stored on a bag item.
    static double
    getBagWeight(List<org.bukkit.inventory.ItemStack> bagContents)
    Calculates the total weight of a list of ItemStacks, typically representing bag contents.
    static double
    getBagWeight(org.bukkit.inventory.ItemStack bag)
    Calculates the total weight of items contained within the specified bag item.
    static String
    getDatabaseType()
    Returns the active database type used by HavenBags.
    static List<org.bukkit.inventory.ItemStack>
    getEtherealBags(String bagId, org.bukkit.entity.Player player)
    Gets the contents of an ethereal bag for a player.
    static EtherealBagSettings
    getEtherealBagSettings(String bagId, org.bukkit.entity.Player player)
    Retrieves settings for a player's ethereal bag.
    static org.bukkit.plugin.java.JavaPlugin
    getInstance()
    Gets the main plugin instance.
    static double
    getItemWeight(org.bukkit.inventory.ItemStack item)
    Retrieves the weight of a single ItemStack.
    static List<Data>
    getOpenBagsUUIDs()
    Returns Data objects for all currently open bags.
    static List<Data>
    getPlayerBags(String playerUUID)
    Lists all bags owned by a player.
    static String
    getTexture(org.bukkit.inventory.ItemStack bag)
    Retrieves the custom texture Base64 string from the specified bag item.
    static valorless.valorlessutils.translate.Translator
    getTranslator()
    Gets the Translator instance used by HavenBags.
    static boolean
    hasEtherialBag(String bagId, org.bukkit.entity.Player player)
    Checks if the player has the specified ethereal bag.
    static boolean
    hasEtherialBags(String bagId, org.bukkit.entity.Player player)
    Checks if the player has any ethereal bags.
    static boolean
    hasOthersBag(org.bukkit.entity.Player player)
    Checks if the player has any bags belonging to other players.
    static boolean
    isBag(org.bukkit.inventory.ItemStack item)
    Checks whether the given item is a HavenBag.
    static boolean
    isBagFull(String uuid)
    Checks if the bag with the specified UUID is full (no empty slots).
    static boolean
    isBagFull(UUID uuid)
    Checks if the bag with the specified UUID is full (no empty slots).
    static boolean
    isBagFull(org.bukkit.inventory.ItemStack bag)
    Checks if the specified bag is full (no empty slots).
    static boolean
    isBagOpen(String uuid)
    Checks if a bag is currently open by any viewer.
    static boolean
    isEtherealBagOpen(String bagId, org.bukkit.entity.Player player)
    Checks if the specified ethereal bag is currently open.
    static boolean
    isItemBlacklisted(org.bukkit.inventory.ItemStack item, Data bagData)
    Checks if the specified item is blacklisted from being stored in HavenBags.
    static boolean
    isToken(org.bukkit.inventory.ItemStack item)
    Checks whether the given item is a valid skin token.
    static void
    refreshBagLore(org.bukkit.inventory.ItemStack bag)
    Refreshes the lore of the specified bag item to reflect its current state.
    static void
    refreshBagLore(org.bukkit.inventory.ItemStack bag, org.bukkit.entity.Player player)
    Refreshes the lore of the specified bag item to reflect its current state.
    static boolean
    removeEtherealBag(String bagId, org.bukkit.entity.Player player)
    Removes an ethereal bag entry from a player.
    static boolean
    setEtherealBagContents(String bagId, org.bukkit.entity.Player player, List<org.bukkit.inventory.ItemStack> contents)
    Replaces the contents of an ethereal bag for a player.
    static void
    setTexture(org.bukkit.inventory.ItemStack bag, String base64Texture)
    Sets a custom texture on the specified bag item.
    static org.bukkit.inventory.ItemStack
    upgradeBag(org.bukkit.inventory.ItemStack bag)
    Upgrades the given bag ItemStack to the next size tier.
    static double
    usedCapacity(org.bukkit.inventory.ItemStack bag)
    Calculates how full the specified bag is.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • HavenBagsAPI

      public HavenBagsAPI()

  • Method Details

    • getInstance

      public static org.bukkit.plugin.java.JavaPlugin getInstance()
      Gets the main plugin instance.
      Returns:
      HavenBags JavaPlugin instance

    • forceCloseAllBags

      public static void forceCloseAllBags()
      Forces the closure of all open bags for all players.

    • getTranslator

      public static valorless.valorlessutils.translate.Translator getTranslator()
      Gets the Translator instance used by HavenBags.
      Returns:
      Translator instance

    • isBag

      public static boolean isBag(org.bukkit.inventory.ItemStack item)
      Checks whether the given item is a HavenBag.
      Parameters:
      item - item to check
      Returns:
      true if the item represents a bag

    • getBagUUID

      public static String getBagUUID(org.bukkit.inventory.ItemStack item)
      Gets the UUID stored on a bag item.
      Parameters:
      item - bag item
      Returns:
      bag UUID string, or null if not a bag

    • getBagData

      public static Data getBagData(org.bukkit.inventory.ItemStack item)
      Resolves the live Data object for the given bag item.
      Parameters:
      item - bag item
      Returns:
      Data for the bag, or null if not a bag

    • generateBagItem

      public static org.bukkit.inventory.ItemStack generateBagItem(Data bagData)
      Generates a bag item from the provided Data.
      Parameters:
      bagData - Data for the bag
      Returns:
      ItemStack representing the bag

    • bagExists

      public static boolean bagExists(String uuid)
      Checks whether a bag exists in storage.
      Parameters:
      uuid - bag UUID
      Returns:
      true if the bag exists

    • getBag

      public static Data getBag(String uuid)
      Fetches Data for a bag by UUID.
      Parameters:
      uuid - bag UUID
      Returns:
      Data for the bag or null if not found

    • getBagOwner

      public static String getBagOwner(String uuid)
      Gets the owner UUID of a bag.
      Parameters:
      uuid - bag UUID
      Returns:
      owner UUID string

    • getPlayerBags

      public static List<Data> getPlayerBags(String playerUUID)
      Lists all bags owned by a player.
      Parameters:
      playerUUID - player UUID
      Returns:
      list of Data for the player's bags

    • getBagsOnPlayer

      public static List<Data> getBagsOnPlayer(org.bukkit.entity.Player player)
      Lists all bag Data instances present in a player's inventory.
      Parameters:
      player - player to inspect
      Returns:
      list of Data for bags found

    • isBagOpen

      public static boolean isBagOpen(String uuid)
      Checks if a bag is currently open by any viewer.
      Parameters:
      uuid - bag UUID
      Returns:
      true if open

    • bagOpenBy

      public static org.bukkit.entity.Player bagOpenBy(String uuid)
      Gets the player who has the bag open.
      Parameters:
      uuid - bag UUID
      Returns:
      Player who opened the bag, or null if not open

    • getOpenBagsUUIDs

      public static List<Data> getOpenBagsUUIDs()
      Returns Data objects for all currently open bags.
      Returns:
      list of open bag Data

    • getDatabaseType

      public static String getDatabaseType()
      Returns the active database type used by HavenBags.
      Returns:
      database type as string. i.e, "FILES", "SQLITE", etc.

    • createBag

      public static Data createBag(BagCreationObject creationObject)
      Creates and persists a new bag from the provided creation descriptor.
      Parameters:
      creationObject - bag creation parameters
      Returns:
      Data for the created bag

    • createBag

      public static Data createBag(Data bagData)
      Creates and persists a new bag from the provided Data object.
      Parameters:
      bagData - bag Data
      Returns:
      Data for the created bag

    • deleteBag

      public static boolean deleteBag(String uuid)
      Deletes a bag by UUID.
      Parameters:
      uuid - bag UUID
      Returns:
      true if deletion succeeded

    • createToken

      public static org.bukkit.inventory.ItemStack createToken(String value, TokenType type)
      Creates a skin token ItemStack for the given value and type.
      Parameters:
      value - token payload (e.g., texture or model key)
      type - token type
      Returns:
      token item

    • createEffectToken

      public static org.bukkit.inventory.ItemStack createEffectToken(String value)
      Creates an effect token for the given effect identifier.
      Parameters:
      value - effect id
      Returns:
      token item

    • isToken

      public static boolean isToken(org.bukkit.inventory.ItemStack item)
      Checks whether the given item is a valid skin token.
      Parameters:
      item - item to test
      Returns:
      true if the item is a skin token

    • createEtherealBag

      public static boolean createEtherealBag(String bagId, org.bukkit.entity.Player player, int size)
      Creates an ethereal bag entry for a player.
      Parameters:
      bagId - bag identifier
      player - target player
      size - inventory size (implementation dependent)
      Returns:
      true on success

    • removeEtherealBag

      public static boolean removeEtherealBag(String bagId, org.bukkit.entity.Player player)
      Removes an ethereal bag entry from a player.
      Parameters:
      bagId - bag identifier
      player - target player
      Returns:
      true on success

    • getEtherealBags

      public static List<org.bukkit.inventory.ItemStack> getEtherealBags(String bagId, org.bukkit.entity.Player player)
      Gets the contents of an ethereal bag for a player.
      Parameters:
      bagId - bag identifier
      player - player owning the bag
      Returns:
      contents as a list of ItemStacks, or null if not found

    • hasEtherialBag

      public static boolean hasEtherialBag(String bagId, org.bukkit.entity.Player player)
      Checks if the player has the specified ethereal bag.
      Parameters:
      bagId - bag identifier
      player - player to check
      Returns:
      true if present

    • hasEtherialBags

      public static boolean hasEtherialBags(String bagId, org.bukkit.entity.Player player)
      Checks if the player has any ethereal bags.
      Parameters:
      bagId - ignored identifier
      player - player to check
      Returns:
      true if the player has one or more ethereal bags

    • isEtherealBagOpen

      public static boolean isEtherealBagOpen(String bagId, org.bukkit.entity.Player player)
      Checks if the specified ethereal bag is currently open.
      Parameters:
      bagId - bag identifier
      player - player owning the bag
      Returns:
      true if open

    • setEtherealBagContents

      public static boolean setEtherealBagContents(String bagId, org.bukkit.entity.Player player, List<org.bukkit.inventory.ItemStack> contents)
      Replaces the contents of an ethereal bag for a player.
      Parameters:
      bagId - bag identifier
      player - player owning the bag
      contents - new contents list
      Returns:
      true on success

    • getEtherealBagSettings

      public static EtherealBagSettings getEtherealBagSettings(String bagId, org.bukkit.entity.Player player)
      Retrieves settings for a player's ethereal bag.
      Parameters:
      bagId - bag identifier
      player - player owning the bag
      Returns:
      the bag's settings, or null if absent

    • upgradeBag

      public static org.bukkit.inventory.ItemStack upgradeBag(org.bukkit.inventory.ItemStack bag)
      Upgrades the given bag ItemStack to the next size tier. Increases the bag size by 9 slots, updates weight limit if applicable, and changes texture based on new size and owner status.
      Parameters:
      bag - The ItemStack representing the bag to upgrade.
      Returns:
      A new ItemStack representing the upgraded bag, or the original bag if already at max size.

    • setTexture

      public static void setTexture(org.bukkit.inventory.ItemStack bag, String base64Texture)
      Sets a custom texture on the specified bag item.
      Parameters:
      bag - The ItemStack representing the bag to modify.
      base64Texture - A valid Base64-encoded string representing the new texture.
      Throws:
      IllegalArgumentException - if the provided texture is not valid Base64.

    • getTexture

      public static String getTexture(org.bukkit.inventory.ItemStack bag)
      Retrieves the custom texture Base64 string from the specified bag item.
      Parameters:
      bag - The ItemStack representing the bag to inspect.
      Returns:
      A Base64-encoded string representing the bag's texture.

    • refreshBagLore

      public static void refreshBagLore(org.bukkit.inventory.ItemStack bag)
      Refreshes the lore of the specified bag item to reflect its current state.
      Parameters:
      bag - The ItemStack representing the bag to refresh.

    • refreshBagLore

      public static void refreshBagLore(org.bukkit.inventory.ItemStack bag, org.bukkit.entity.Player player)
      Refreshes the lore of the specified bag item to reflect its current state.
      Parameters:
      bag - The ItemStack representing the bag to refresh.
      player - The player used in placeholder parsing.

    • getBagWeight

      public static double getBagWeight(org.bukkit.inventory.ItemStack bag)
      Calculates the total weight of items contained within the specified bag item.
      Parameters:
      bag - The ItemStack representing the bag to evaluate.
      Returns:
      The total weight of the bag's contents.

    • getBagWeight

      public static double getBagWeight(List<org.bukkit.inventory.ItemStack> bagContents)
      Calculates the total weight of a list of ItemStacks, typically representing bag contents.
      Parameters:
      bagContents - A list of ItemStacks to evaluate.
      Returns:
      The total weight of the provided items.

    • getItemWeight

      public static double getItemWeight(org.bukkit.inventory.ItemStack item)
      Retrieves the weight of a single ItemStack.
      Parameters:
      item - The ItemStack to evaluate.
      Returns:
      The weight of the specified item.

    • canCarry

      public static boolean canCarry(org.bukkit.inventory.ItemStack item, org.bukkit.inventory.ItemStack bag)
      Checks if the specified item can be carried in the given bag, considering weight limits.
      Parameters:
      item - The ItemStack to check.
      bag - The ItemStack representing the bag.
      Returns:
      true if bag cannot hold more weight, false otherwise.

    • isItemBlacklisted

      public static boolean isItemBlacklisted(org.bukkit.inventory.ItemStack item, @Nullable Data bagData)
      Checks if the specified item is blacklisted from being stored in HavenBags.

      Takes into account if using blacklist or whitelist mode.
      Please check the blacklistAsWhitelist(Data bagData) before calling this method to ensure correct context.
      For global context refer to blacklistAsWhitelist().

      Parameters:
      item - The ItemStack to check.
      bagData - (Optional) The Data object of the bag for context-specific checks; can be null.
      Returns:
      true if the item is blacklisted, false otherwise.

    • blacklistAsWhitelist

      public static boolean blacklistAsWhitelist()
      Checks if the global configuration is set to treat the blacklist as a whitelist.
      Returns:
      true if blacklist is used as whitelist, false otherwise.

    • blacklistAsWhitelist

      public static boolean blacklistAsWhitelist(Data bagData)
      Checks if the specified bag's configuration is set to treat its blacklist as a whitelist.
      Parameters:
      bagData - The Data object of the bag to check.
      Returns:
      true if blacklist is used as whitelist for this bag, false otherwise.

    • canCarryMoreBags

      public static boolean canCarryMoreBags(org.bukkit.entity.Player player)
      Checks if the player can carry more bags based on configured limits.
      Parameters:
      player - The player to check.
      Returns:
      true if the player can carry more bags, false otherwise.

    • isBagFull

      public static boolean isBagFull(org.bukkit.inventory.ItemStack bag)
      Checks if the specified bag is full (no empty slots).
      Parameters:
      bag - The ItemStack representing the bag to check.
      Returns:
      true if the bag is full, false otherwise.

    • isBagFull

      public static boolean isBagFull(UUID uuid)
      Checks if the bag with the specified UUID is full (no empty slots).
      Parameters:
      uuid - The UUID string of the bag to check.
      Returns:
      true if the bag is full, false otherwise.

    • isBagFull

      public static boolean isBagFull(String uuid)
      Checks if the bag with the specified UUID is full (no empty slots).
      Parameters:
      uuid - The UUID string of the bag to check.
      Returns:
      true if the bag is full, false otherwise.

    • bagSlotsEmpty

      public static int bagSlotsEmpty(org.bukkit.inventory.ItemStack bag)
      Counts the number of empty slots in the specified bag item.
      Parameters:
      bag - The ItemStack representing the bag to check.
      Returns:
      The number of empty slots in the bag.

    • usedCapacity

      public static double usedCapacity(org.bukkit.inventory.ItemStack bag)
      Calculates how full the specified bag is.
      Parameters:
      bag - The ItemStack representing the bag to evaluate.
      Returns:
      The percentage of used capacity in the bag (0.0 to 100.0).

    • getBagSlotsInInventory

      public static int getBagSlotsInInventory(org.bukkit.entity.Player player)
      Calculates the total number of bag slots in a player's inventory.
      Parameters:
      player - The player whose inventory to check.
      Returns:
      The total number of bag slots.

    • hasOthersBag

      public static boolean hasOthersBag(org.bukkit.entity.Player player)
      Checks if the player has any bags belonging to other players.
      Parameters:
      player - The player to check.
      Returns:
      true if the player has bags owned by others, false otherwise.

    • capacityTexture

      public static String capacityTexture(org.bukkit.inventory.ItemStack bag)
      Determines the appropriate texture for a bag based on its used capacity. (e.g., changes texture as the bag fills up)
      Parameters:
      bag - The ItemStack representing the bag to evaluate.
      Returns:
      A Base64-encoded string representing the texture for the bag's current capacity.
      If no special texture is defined in the configuration, returns the bag's current texture.

    • bagState

      public static String bagState(org.bukkit.inventory.ItemStack item)
      Retrieves the current state of the bag.
      Parameters:
      item - The ItemStack representing the bag to evaluate.
      Returns:
      "NEW" if the bag is empty, "USED" otherwise.
      May return "NULL" if the item is not a valid bag.

    • extractUrlFromBase64

      public static String extractUrlFromBase64(String base64)
      Extracts the URL from a Base64-encoded texture string.
      Parameters:
      base64 - The Base64-encoded texture string.
      Returns:
      The extracted URL.

    • convertUrlToBase64

      public static String convertUrlToBase64(String url)
      Converts a texture URL to a Base64-encoded string.
      Parameters:
      url - The texture URL.
      Returns:
      The Base64-encoded texture string.

    • creteHeadFromBase64

      public static org.bukkit.inventory.ItemStack creteHeadFromBase64(String base64)
      Creates a player head ItemStack with a custom texture from a Base64 string.
      Parameters:
      base64 - The Base64-encoded texture string.
      Returns:
      The custom player head ItemStack.

    • createUnusedBagItem

      public static org.bukkit.inventory.ItemStack createUnusedBagItem(int size, boolean binding)
      Creates an unused bag ItemStack with specified size and binding status.
      Parameters:
      size - The size of the bag (number of slots, to the power of 9).
      binding - Whether the bag should be bound to an owner upon creation.
      Returns:
      The created unused bag ItemStack.