Items and NBT

Items and NBT

EverNifeCore builds ItemStacks through a fluent builder that adds NBT support and color-code parsing on top of the familiar triumph-gui item builder. It also carries a small item-data-part system: a string-list representation of an item you can store in config and rebuild later, plus a composable item-comparison layer.

Building items

FCItemFactory is the entry point. Every factory method returns an FCItemBuilder:

import br.com.finalcraft.evernifecore.minecraft.itemstack.FCItemFactory;
import br.com.finalcraft.evernifecore.minecraft.itemstack.itembuilder.FCItemBuilder;

FCItemBuilder builder = FCItemFactory.from(Material.DIAMOND_SWORD);
FCItemFactory.from("minecraft:diamond_sword");   // Bukkit OR Minecraft identifier
FCItemFactory.from(existingItemStack);           // clones the stack into a builder
FCItemFactory.itemBuilder();                     // starts from STONE

The builder is fluent; build() produces the finished ItemStack:

ItemStack reward = FCItemFactory.from(Material.DIAMOND_SWORD)
        .displayName("&bExcalibur")              // color codes are translated for you
        .lore("&7A legendary blade", "&7+10 damage")
        .amount(1)
        .addEnchant(Enchantment.DAMAGE_ALL, 5)
        .addItemFlags(ItemFlag.HIDE_ATTRIBUTES)
        .setGlow()
        .setUnbreakable()
        .build();

Common builder methods:

Method	Effect
displayName(String)	Sets the name; color codes translated via FCColorUtil.
lore(String...) / lore(List<String>)	Sets lore; color-translated, split on \n.
lore(Consumer<List<String>>) / lore(Function<...>)	Edit the existing lore in place.
amount(int) / durability(int)	Stack size / durability.
material(Material | String | ItemStack)	Swap the material, copying meta across.
addEnchant(Enchantment[, level[, ignoreLevelRestriction]])	Add an enchantment.
removeEnchantment(Enchantment)	Remove an enchantment.
addItemFlags(ItemFlag...)	Hide attributes/enchants/etc.
setGlow([boolean])	Enchant-glow without visible enchants (uses a durability enchant on 1.7.10).
setUnbreakable([boolean])	Unbreakable flag (falls back to raw NBT on legacy versions).
setCustomModelData(int)	Custom model data (1.13+; no-op below).
setColor(Color)	Dye color for leather armor.
setPDC(Consumer<PersistentDataContainer>)	Edit the persistent data container (1.14+).

The builder clones its source item, so the original stack is never mutated. It also validates the handle through NMS where available; AIR is rejected.

Converting to other shapes

FCItemBuilder can hand the finished stack straight to the GUI and layout systems, or to any class with a single-ItemStack constructor:

builder.asGuiItem();          // a triumph-gui GuiItem
builder.asGuiItemComplex();   // an auto-updating GuiItemComplex (see the GUI page)
builder.asLayout();           // a LayoutIcon for the layout system
builder.as(MyHolder.class);   // any class with a (ItemStack) constructor

There are also apply(Consumer<FCItemBuilder>) and applyIf(Supplier<Boolean>, Consumer<...>) for conditional builder branches, and applyMaterialIfExists(String) which swaps the material only if the identifier resolves on this server version.

NBT

NBT support is provided by the bundled Item-NBT-API (de.tr7zw.changeme.nbtapi). The builder holds an internal NBTCompound copy of the item (with the redundant display key removed, since name and lore live on the meta); it is merged onto the item at build().

ItemStack tagged = FCItemFactory.from(Material.PAPER)
        .displayName("&eQuest Token")
        .setNbt(nbt -> {
            nbt.setString("quest_id", "find_the_key");
            nbt.setInteger("stage", 2);
        })
        .build();

setNbt(Consumer<NBTCompound>) is the lambda form used above. setNbt(NBTCompound) replaces the whole compound (it clears the current one, then merges). getNBTCompound() returns the live compound if you need to read or edit it directly.

The NBT layer needs Item-NBT-API to resolve the server's NMS mappings. On startup the plugin runs an NBT self-test and logs the outcome; if it fails (some non-standard forks), item/GUI NBT is disabled but the rest of the plugin still starts. See Version Compatibility.

Item data parts

ItemDataPart turns an ItemStack into a list of "key:value" strings, and back. This is what makes an item human-editable in a YAML file. Each part is a named piece of the item, applied in a fixed priority order (material first, then the rest).

import br.com.finalcraft.evernifecore.minecraft.itemdatapart.ItemDataPart;

// Item -> string list (round-trips through config).
List<String> data = ItemDataPart.readItem(item);
// e.g. [ "type:DIAMOND_SWORD", "amount:1", "name:&bExcalibur", "lore:&7...", "nbt:{...}" ]

// String list -> item.
ItemStack rebuilt = ItemDataPart.transformItem(data);

The builder exposes the same round-trip: FCItemBuilder.toDataPart() equals readItem(build()), and FCItemFactory.from(List<String>) runs transformItem. The recognised part keys (each accepts a few aliases) are:

Part	Keys
Material	type, id, material, identifier
Durability	damage, durability, subid
Amount	amount, number
Name	name, text, title
Lore	lore, description
Item flags	flag, flags, itemflag, hideflag, ...
Custom model data	CustomModelData
NBT	nbt, rawnbt
Enchantment	enchant (registered only on 1.21+)

Parts whose data type is unsupported on the running server version are skipped rather than failing the whole item, and an unreadable line is logged and ignored.

Comparing items

ComparableItem is a lightweight value-matcher: two items match when their material (and, for ComparableItemComplex, their NBT) agree. ItemDataPart.isSimilar(base, other, exceptions, compareAmount) compares two stacks part-by-part, letting you exclude specific parts (for example, ignore AMOUNT). These are the primitives shops and reward systems use to recognise a configured item at runtime.

See also

• GUI Framework - asGuiItem / asGuiItemComplex and the layout system.
• Configuration - ItemStack is a registered config type, so you can store one directly.
• Version Compatibility - which item features exist on which Minecraft version.
• Integrations - BossShopPro item translation uses the data-part layer.