Class HeirloomAPI

java.lang.Object
ke.ric.api.HeirloomAPI
public class HeirloomAPI extends Object
Main API entry point for Heirloom addons. Addons should get this instance via: 
HeirloomAPI api = HeirloomAPI.getInstance();
Or during plugin enable: 
Plugin heirloom = getServer().getPluginManager().getPlugin("Heirloom");
if (heirloom != null && heirloom.isEnabled()) {
    HeirloomAPI api = HeirloomAPI.getInstance();
    // Register your addon
    api.registerAddon(this, new MyAddon());
}

  • Method Details

    • registerReloadState

      public void registerReloadState(String addonId, Supplier<Runnable> snapshot)
      Include a small addon-owned rule snapshot in the existing registration transaction.

    • getInstance

      public static HeirloomAPI getInstance()
      Get the HeirloomAPI instance.
      Returns:
      The singleton HeirloomAPI instance (check isReady() before invoking runtime helpers)

    • isReady

      public boolean isReady()
      Check whether Heirloom is enabled and registrations/lookups are ready for use.
      Returns:
      true when Heirloom has initialized its managers and is enabled

    • foodFacts

      public FoodFacts foodFacts(org.bukkit.inventory.ItemStack item)
      Read immutable, versioned dietary provenance from an item stack.

    • foodFactsV2

      public FoodFactsV2 foodFactsV2(org.bukkit.inventory.ItemStack item)
      Read source-qualified ingredient and dietary evidence without modifying the item.

    • registerAddon

      public void registerAddon(String addonId, String version, org.bukkit.plugin.Plugin owningPlugin, Consumer<HeirloomAPI> registrationCallback)
      Register an addon with Heirloom using a callback. This method avoids classloader issues by not requiring the addon to implement HeirloomAddon.
      Parameters:
      addonId - Unique addon identifier (e.g., "distillery")
      version - Addon version string
      owningPlugin - The plugin that owns the addon
      registrationCallback - Called to register addon content (receives HeirloomAPI)

    • registerAddon

      public void registerAddon(String addonId, String version, org.bukkit.plugin.Plugin owningPlugin, Consumer<HeirloomAPI> registrationCallback, Runnable reloadCallback)
      Register an addon with Heirloom using callbacks for enable and reload.
      Parameters:
      addonId - Unique addon identifier
      version - Addon version string
      owningPlugin - The plugin that owns the addon
      registrationCallback - Called to register addon content
      reloadCallback - Called when Heirloom reloads

    • registerAddon

      public void registerAddon(String addonId, String version, org.bukkit.plugin.Plugin owningPlugin, Consumer<HeirloomAPI> registrationCallback, Runnable reloadCallback, Runnable disableCallback)
      Callback variant including owner cleanup when the addon is removed independently of its plugin.

    • reloadAddons

      public void reloadAddons()
      Reload all registered addons and refresh recipe browser state. External callers retain the historical refresh behavior.

    • snapshotReloadRegistrations

      public HeirloomAPI.ReloadRollbackScope snapshotReloadRegistrations()
      Snapshot every registry exposed to addon callbacks. The snapshot must be taken before core managers reload because those reloads also replace main indexes containing addon registrations.

    • registerAddon

      public void registerAddon(org.bukkit.plugin.Plugin owningPlugin, HeirloomAddon addon)
      Register an addon with Heirloom (legacy method - for backwards compatibility). NOTE: This requires the addon class to implement HeirloomAddon, which can cause classloader issues. Prefer registerAddon(id, version, plugin, callback) instead.
      Parameters:
      owningPlugin - The plugin that owns the addon
      addon - The addon implementation

    • unregisterAddon

      public void unregisterAddon(String addonId)
      Unregister an addon.

    • refreshContentViewsAfterCommit

      public void refreshContentViewsAfterCommit()
      Publish registry changes to every read-only content view after an external transaction has committed. Refresh failures cannot roll back an already committed registry; each view keeps its prior coherent snapshot instead.

    • withAddonRegistrationContext

      public void withAddonRegistrationContext(String addonId, Runnable registration)
      Run an explicitly requested addon refresh through all existing owner-scoped registries.

    • getAddon

      public HeirloomAddon getAddon(String addonId)
      Get a registered addon by ID.

    • isAddonRegistered

      public boolean isAddonRegistered(String addonId)
      Check if an addon is registered.

    • items

      public ItemRegistration items()
      Get the item registration API. Use this to register custom items programmatically.

    • crops

      public CropRegistration crops()
      Get the crop registration API. Use this to register custom crops programmatically.

    • seedAcquisition

      public SeedAcquisitionRegistration seedAcquisition()
      Additive seed packet, grass-drop, and chest-loot registration for addons.

    • properties

      public PropertyRegistration properties()
      Get the dietary property registration API. Use this to register custom dietary properties.

    • recipes

      public RecipeRegistration recipes()
      Get the recipe registration API. Use this to register custom recipes for your addon.

    • aging

      public AgingRegistration aging()
      Get the owner-scoped staged aging registration API.

    • advancements

      public AdvancementRegistration advancements()
      Get the owner-scoped native advancement registration API.

    • guides

      public GuideRegistration guides()
      Get the owner-scoped immutable addon guide registration API.

    • createItem

      public org.bukkit.inventory.ItemStack createItem(String itemId)
      Create a custom item by ID.
      Parameters:
      itemId - The custom item ID
      Returns:
      The ItemStack, or null if not found

    • createItem

      public org.bukkit.inventory.ItemStack createItem(String itemId, int amount)
      Create a custom item with a specific amount.

    • isCustomItem

      public boolean isCustomItem(org.bukkit.inventory.ItemStack item)
      Check if an ItemStack is a Heirloom custom item.

    • getCustomItemId

      public String getCustomItemId(org.bukkit.inventory.ItemStack item)
      Get the custom item ID from an ItemStack.