> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sentrystudios.org/llms.txt
> Use this file to discover all available pages before exploring further.

# SentryLore

> How to integrate SentryLore into your own custom plugins.

SentryLore exposes several methods and managers to allow developers to interact with the lore engine, format custom items dynamically, or hook into the custom item registry.

## Getting the Plugin Instance

To interact with SentryLore's core managers, you can grab the main plugin instance using the static `getPlugin()` method.

<CodeGroup>
  ```java Java theme={null}
  import me.sentrystudios.sentrylore.SentryLore;

  public class MyPlugin {
      public void doSomething() {
          SentryLore api = SentryLore.getPlugin();
          
          // Access the Database Manager
          api.getDatabaseManager();
          
          // Access the Configuration Manager
          api.getConfigManager();
      }
  }
  ```

  ```kotlin Kotlin theme={null}
  import me.sentrystudios.sentrylore.SentryLore

  class MyPlugin {
      fun doSomething() {
          val api = SentryLore.getPlugin()
          
          // Access the Database Manager
          api.databaseManager
          
          // Access the Configuration Manager
          api.configManager
      }
  }
  ```
</CodeGroup>

***

## Example 1: Creating Custom Loot Crates

If you are developing a custom Crates plugin or a webstore package distributor, you can hook into the SentryLore database to spawn in legendary items that an administrator saved via `/lore save`.

This ensures that the items spawned are exactly how the admin configured them in-game, complete with unique Dupe Protection NBT tags.

<CodeGroup>
  ```java Paper theme={null}
  import me.sentrystudios.sentrylore.SentryLore;
  import me.sentrystudios.sentrylore.utils.ItemSerializer;
  import org.bukkit.inventory.ItemStack;
  import org.bukkit.entity.Player;

  public void giveRegistryItem(Player player, String customId) {
      // 1. Fetch the serialized base64 string from the database
      String base64Data = SentryLore.getPlugin().getDatabaseManager().loadCustomItem(customId.toLowerCase());
      
      if (base64Data != null) {
          // 2. Deserialize it back into a Bukkit ItemStack
          ItemStack item = ItemSerializer.deserialize(base64Data);
          
          if (item != null) {
              // 3. Give it to the player safely on the main thread
              player.getInventory().addItem(item);
          }
      }
  }
  ```

  ```kotlin Kotlin theme={null}
  import me.sentrystudios.sentrylore.SentryLore
  import me.sentrystudios.sentrylore.utils.ItemSerializer
  import org.bukkit.entity.Player

  fun giveRegistryItem(player: Player, customId: String) {
      // 1. Fetch the serialized base64 string from the database
      val base64Data = SentryLore.getPlugin().databaseManager.loadCustomItem(customId.lowercase())
      
      if (base64Data != null) {
          // 2. Deserialize it back into a Bukkit ItemStack
          val item = ItemSerializer.deserialize(base64Data)
          
          if (item != null) {
              // 3. Give it to the player
              player.inventory.addItem(item)
          }
      }
  }
  ```
</CodeGroup>

***

## Example 2: Forcing Lore on Custom Mobs

SentryLore automatically formats vanilla items when they are picked up or moved. However, if you have a custom plugin that spawns a boss mob with custom drops, you can force the SentryLore engine to apply its RPG formatting (rarity, stats, classes) *before* the item even hits the ground!

You achieve this using the `LoreFormatter` utility class.

<CodeGroup>
  ```java Paper theme={null}
  import me.sentrystudios.sentrylore.utils.LoreFormatter;
  import org.bukkit.inventory.ItemStack;
  import org.bukkit.Material;

  public ItemStack createBossDrop() {
      ItemStack customLoot = new ItemStack(Material.DIAMOND_SWORD);
      
      // Force SentryLore to apply the RPG rarity, stats, and lore 
      // to this specific item immediately!
      LoreFormatter.formatVanillaItem(customLoot);
      
      return customLoot;
  }
  ```

  ```kotlin Kotlin theme={null}
  import me.sentrystudios.sentrylore.utils.LoreFormatter
  import org.bukkit.inventory.ItemStack
  import org.bukkit.Material

  fun createBossDrop(): ItemStack {
      val customLoot = ItemStack(Material.DIAMOND_SWORD)
      
      // Force SentryLore to apply the RPG rarity, stats, and lore 
      // to this specific item immediately!
      LoreFormatter.formatVanillaItem(customLoot)
      
      return customLoot
  }
  ```
</CodeGroup>

<Warning>
  `formatVanillaItem(item)` modifies the `ItemStack` directly (passed by reference). Ensure you apply it before displaying the item to the player! If you want to STRIP existing SentryLore formatting and re-apply it (e.g., if you changed the item's attributes), use `LoreFormatter.forceReformat(customLoot);` instead.
</Warning>