> ## 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.

```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
    }
}
```

## Core API Reference

### Database Item Registry

**customId** `string` *required*

The unique alphanumeric ID of the saved custom item in the database (e.g. `excalibur_v1`).

**base64Data** `String`

The serialized Bukkit `ItemStack` encoded as a Base64 string, containing all NBT data, lore lines, and persistent dupe tokens. Returns `null` if the item is not registered.

**Persistent NBT Metadata**

**sentrylore\_uuid** `UUID`

Cryptographic tracking identifier injected into `PersistentDataContainer` (PDC). Verified across all inventory move, click, and drop events to prevent duplication exploits.

**sentrylore\_category** `String`

The small-caps category string (`SWORD`, `BOW`, `ARMOR`, `TOOL`, `CANVAS`, `MISC`).

**sentrylore\_tier** `String`

The active rarity tier (`COMMON`, `UNCOMMON`, `RARE`, `EPIC`, `LEGENDARY`, `MYTHICAL`).

***

## 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.

```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)
        }
    }
}
```

***

## 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.

```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
}
```

> [!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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.