BedrioxDOCUMENTATION
PLUGIN DEVELOPMENT

Custom NBT

Bedriox exposes typed, bounded NBT values for plugin-owned item data. Use Bedriox\Api\Nbt\Tag factories rather than raw binary encoders.

Create scalar tags, lists, and compounds with explicit types and bounded keys. Attach plugin data through the item NBT API, then create a new immutable ItemStack carrying that data.

PHP
use Bedriox\Api\Inventory\ItemNbt;
use Bedriox\Api\Inventory\ItemStack;
use Bedriox\Api\Nbt\Tag;

$nbt = ItemNbt::empty()
    ->withString('myplugin:arena_id', 'duels')
    ->withTag('myplugin:reward_level', Tag::int(3));

$arenaTicket = new ItemStack(
    identifier: 'minecraft:paper',
    count: 1,
    nbt: $nbt,
);

$arenaId = $arenaTicket->nbt?->string('myplugin:arena_id');

$nbt is a new immutable compound after each chained call. $arenaTicket is the item stack carrying that compound, and $arenaId is either the stored string or null when the key is absent or has a different NBT type.

Keep custom keys under a unique plugin namespace such as example:arena_id. Do not overwrite vanilla or another plugin's keys.

Check a tag's type before reading it, treat missing values as normal, bound list and string sizes, and provide a migration path if your stored format changes. NBT is persistent data—not a place for PHP objects, serialized values, secrets, or executable configuration.