NBT API

For a full list of wiki pages, see the Home page.

NBT API

DPP-Core provides a simple and convenient NBT (Named Binary Tag) API that acts as a wrapper around Bukkit's PersistentDataContainer. This API makes it easy to store custom data on ItemStacks without needing to work directly with NamespacedKeys.

Core Classes

• NBTAPI: A static utility class that serves as the entry point for all NBT operations.
• NBTItem: A wrapper class for an ItemStack that provides methods to get and set NBT data.

Modifying NBT Data

To add or change NBT data on an item, you use the NBTAPI.modify method. It takes an ItemStack and a Consumer<NBTItem>, giving you a safe context to perform your modifications.

import com.darksoldier1404.dppc.nbt.NBTAPI;
import org.bukkit.inventory.ItemStack;

// Assume 'item' is your ItemStack
ItemStack modifiedItem = NBTAPI.modify(item, nbt -> {
    nbt.setString("custom_id", "quest_item_123");
    nbt.setInteger("power_level", 99);
    nbt.setBoolean("is_soulbound", true);
});

Setter Methods

The NBTItem class provides setters for various primitive data types and their array counterparts:

• setString(String key, String value)
• setInteger(String key, int value)
• setDouble(String key, double value)
• setBoolean(String key, boolean value)
• setLong(String key, long value)
• setFloat(String key, float value)
• setByte(String key, byte value)
• setShort(String key, short value)
• setIntArray(String key, int[] value)
• setByteArray(String key, byte[] value)

Reading NBT Data

To read NBT data from an item, you use the NBTAPI.get method. It takes the ItemStack and a Function<NBTItem, T> that returns the value you want.

String customId = NBTAPI.get(item, nbt -> nbt.getString("custom_id"));

if ("quest_item_123".equals(customId)) {
    // This is the quest item!
}

Getter Methods

Getter methods are available for all supported data types. They are designed to be safe and will return a default value (e.g., null, 0, false) if the tag does not exist.

• getString(String key)
• getInteger(String key)
• getDouble(String key)
• getBoolean(String key)
• getLong(String key)
• etc.

Checking for Tags

You can check if a tag exists on an item using hasTag.

boolean isSpecial = NBTAPI.get(item, nbt -> nbt.hasTag("is_special"));

if (isSpecial) {
    // Do something special
}

Practical Example: Custom Item Identification

The NBT API is ideal for marking items to prevent them from being stacked with normal items or to identify them for custom behaviors.

import com.darksoldier1404.dppc.builder.itemstack.ItemStackBuilder;
import com.darksoldier1404.dppc.nbt.NBTAPI;
import org.bukkit.Material;
import org.bukkit.inventory.ItemStack;

// Create a special, non-stackable wand
public ItemStack createMagicWand() {
    ItemStack wand = ItemStackBuilder.of(Material.STICK)
        .name("&dMagic Wand")
        .lore("&7A simple stick with a magical aura.")
        .build();

    // Add a unique NBT tag to identify it
    return NBTAPI.modify(wand, nbt -> {
        nbt.setString("wand_id", UUID.randomUUID().toString());
    });
}

// Check if an item is a magic wand in an event
@EventHandler
public void onPlayerInteract(PlayerInteractEvent event) {
    ItemStack item = event.getItem();
    if (item == null) return;

    String wandId = NBTAPI.get(item, nbt -> nbt.getString("wand_id"));

    if (wandId != null) {
        event.getPlayer().getWorld().strikeLightning(event.getPlayer().getTargetBlock(null, 100).getLocation());
        event.setCancelled(true);
    }
}