Item API - PocketMine-MP

Overview

The Item API provides comprehensive control over item instances, including NBT data, enchantments, custom names, and item interactions.

Item Class

The base class for all item types. Namespace: pocketmine\item\Item

Core Methods

getTypeId

public function getTypeId() : int

Returns the numeric type ID of this item.

return

int

The item type ID

// Example: Check item type
if($item->getTypeId() === ItemTypeIds::DIAMOND){
    $player->sendMessage("You have a diamond!");
}

getStateId

public function getStateId() : int

Returns the state ID including item properties.

return

int

The complete item state ID

getName

public function getName() : string

Returns the name of the item (custom name if set, otherwise vanilla name).

return

string

The item’s display name

getVanillaName

public function getVanillaName() : string

Returns the vanilla name, ignoring custom names.

return

string

The vanilla item name

Count & Stack

getCount

public function getCount() : int

Returns the number of items in this stack.

return

int

Item count

setCount

public function setCount(int $count) : Item

Sets the number of items in this stack.

count

int

required

New item count

return

Item

Returns $this for method chaining

// Example: Set item count
$item->setCount(64);
$player->getInventory()->addItem($item);

pop

public function pop(int $count = 1) : Item

Pops items from the stack and returns them.

count

int

default:"1"

Number of items to pop

return

Item

Clone of this item with the popped amount

// Example: Split item stack
$original = VanillaItems::DIAMOND()->setCount(64);
$popped = $original->pop(32); // $original now has 32, $popped has 32

getMaxStackSize

public function getMaxStackSize() : int

Returns the maximum stack size for this item.

return

int

Maximum stack size (usually 64)

isNull

public function isNull() : bool

Returns whether this item stack is empty.

return

bool

True if count is 0 or less

Custom Name & Lore

hasCustomName

public function hasCustomName() : bool

Returns whether this item has a custom name.

getCustomName

public function getCustomName() : string

Returns the custom name of this item.

return

string

The custom name, or empty string if not set

setCustomName

public function setCustomName(string $name) : Item

Sets a custom name for this item.

name

string

required

Custom name to set

return

Item

Returns $this for method chaining

// Example: Set custom name
$item = VanillaItems::DIAMOND_SWORD();
$item->setCustomName("Legendary Sword");
$player->getInventory()->addItem($item);

clearCustomName

public function clearCustomName() : Item

Removes the custom name from this item.

getLore

public function getLore() : array

Returns the lore (description lines) of this item.

return

string[]

Array of lore lines

setLore

public function setLore(array $lines) : Item

Sets the lore for this item.

lines

string[]

required

Array of lore lines

return

Item

Returns $this for method chaining

// Example: Set item lore
$item = VanillaItems::DIAMOND_SWORD();
$item->setLore([
    "A powerful weapon",
    "Forged in ancient times",
    "Rarity: Legendary"
]);
$player->getInventory()->addItem($item);

NBT Data

hasNamedTag

public function hasNamedTag() : bool

Returns whether this item has NBT data.

getNamedTag

public function getNamedTag() : CompoundTag

Returns the item’s NBT data.

return

CompoundTag

NBT compound tag

use pocketmine\nbt\tag\StringTag;

// Example: Set custom NBT data
$nbt = $item->getNamedTag();
$nbt->setString("CustomData", "some_value");
$item->setNamedTag($nbt);

// Example: Read custom NBT data
$nbt = $item->getNamedTag();
if($nbt->getTag("CustomData") instanceof StringTag){
    $value = $nbt->getString("CustomData");
}

setNamedTag

public function setNamedTag(CompoundTag $tag) : Item

Sets the item’s NBT data.

tag

CompoundTag

required

NBT data to set

clearNamedTag

public function clearNamedTag() : Item

Removes all NBT data from the item.

Keep on Death

keepOnDeath

public function keepOnDeath() : bool

Returns whether players retain this item on death.

setKeepOnDeath

public function setKeepOnDeath(bool $keepOnDeath) : void

Sets whether this item is kept on death.

keepOnDeath

bool

required

Whether to keep on death

// Example: Make item persistent on death
$item = VanillaItems::COMPASS();
$item->setKeepOnDeath(true);
$player->getInventory()->addItem($item);

Comparison

equals

public function equals(Item $item, bool $checkDamage = true, bool $checkCompound = true) : bool

Compares this item to another.

item

Item

required

Item to compare with

checkDamage

bool

default:"true"

Deprecated parameter

checkCompound

bool

default:"true"

Whether to check NBT data

return

bool

True if items match

canStackWith

public function canStackWith(Item $other) : bool

Returns whether this item can stack with another.

other

Item

required

Item to check stacking with

return

bool

True if items can stack

// Example: Check if items can stack
if($item1->canStackWith($item2)){
    $combined = $item1->getCount() + $item2->getCount();
    $item1->setCount(min($combined, $item1->getMaxStackSize()));
}

Block Interaction

canBePlaced

public function canBePlaced() : bool

Returns whether this item can be placed as a block.

getBlock

public function getBlock(?int $clickedFace = null) : Block

Returns the block corresponding to this item.

clickedFace

int|null

Face that was clicked when placing

return

Block

The block form of this item

Combat & Tools

getAttackPoints

public function getAttackPoints() : int

Returns damage dealt when used as a weapon.

return

int

Attack damage

getDefensePoints

public function getDefensePoints() : int

Returns armor points when worn.

return

int

Defense points

getBlockToolType

public function getBlockToolType() : int

Returns the tool type for block breaking.

return

int

Tool type constant

getBlockToolHarvestLevel

public function getBlockToolHarvestLevel() : int

Returns the harvest level of this tool.

return

int

Harvest level (0 for non-tiered tools)

getMiningEfficiency

public function getMiningEfficiency(bool $isCorrectTool) : float

Returns mining efficiency multiplier.

isCorrectTool

bool

required

Whether this is the correct tool type

Actions & Events

onInteractBlock

public function onInteractBlock(Player $player, Block $blockReplace, Block $blockClicked, int $face, Vector3 $clickVector, array &$returnedItems) : ItemUseResult

Called when a player uses this item on a block.

player

Player

required

Player using the item

blockReplace

Block

required

Block being replaced

blockClicked

Block

required

Block that was clicked

face

int

required

Face of the block clicked

clickVector

Vector3

required

Exact click position

returnedItems

Item[]

Items to return to player

return

ItemUseResult

Result of the interaction

onClickAir

public function onClickAir(Player $player, Vector3 $directionVector, array &$returnedItems) : ItemUseResult

Called when a player uses this item in air.

player

Player

required

Player using the item

directionVector

Vector3

required

Direction the player is facing

returnedItems

Item[]

Items to return to player

onReleaseUsing

public function onReleaseUsing(Player $player, array &$returnedItems) : ItemUseResult

Called when a player releases this item after using it.

onDestroyBlock

public function onDestroyBlock(Block $block, array &$returnedItems) : bool

Called when this item is used to destroy a block.

block

Block

required

Block being destroyed

returnedItems

Item[]

Items to return

return

bool

Whether the item changed

onAttackEntity

public function onAttackEntity(Entity $victim, array &$returnedItems) : bool

Called when this item is used to attack an entity.

victim

Entity

required

Entity being attacked

returnedItems

Item[]

Items to return

Enchantments

hasEnchantment

public function hasEnchantment(Enchantment $enchantment, int $level = -1) : bool

Returns whether this item has the specified enchantment.

enchantment

Enchantment

required

Enchantment to check for

level

int

default:"-1"

Specific level to check (-1 = any level)

use pocketmine\item\enchantment\VanillaEnchantments;

// Example: Check for enchantment
if($item->hasEnchantment(VanillaEnchantments::SHARPNESS())){
    $player->sendMessage("This weapon has Sharpness!");
}

getEnchantment

public function getEnchantment(Enchantment $enchantment) : ?EnchantmentInstance

Returns the enchantment instance if present.

return

EnchantmentInstance|null

The enchantment instance, or null

addEnchantment

public function addEnchantment(EnchantmentInstance $enchantment) : Item

Adds an enchantment to this item.

enchantment

EnchantmentInstance

required

Enchantment to add

use pocketmine\item\enchantment\EnchantmentInstance;
use pocketmine\item\enchantment\VanillaEnchantments;

// Example: Add enchantment
$item = VanillaItems::DIAMOND_SWORD();
$item->addEnchantment(new EnchantmentInstance(VanillaEnchantments::SHARPNESS(), 5));
$item->addEnchantment(new EnchantmentInstance(VanillaEnchantments::UNBREAKING(), 3));
$player->getInventory()->addItem($item);

removeEnchantment

public function removeEnchantment(Enchantment $enchantment, int $level = -1) : Item

Removes an enchantment from this item.

removeEnchantments

public function removeEnchantments() : Item

Removes all enchantments from this item.

getEnchantments

public function getEnchantments() : array

Returns all enchantments on this item.

return

EnchantmentInstance[]

Array of enchantment instances

Fuel & Fire Resistance

getFuelTime

public function getFuelTime() : int

Returns furnace burn time in ticks.

return

int

Fuel time in ticks

getFuelResidue

public function getFuelResidue() : Item

Returns the item left after burning as fuel.

isFireProof

public function isFireProof() : bool

Returns whether this item can survive fire/lava.

Cooldowns

getCooldownTicks

public function getCooldownTicks() : int

Returns cooldown duration in ticks.

getCooldownTag

public function getCooldownTag() : ?string

Returns the cooldown group tag.

VanillaItems Helper

Provides easy access to vanilla item types. Namespace: pocketmine\item\VanillaItems

Usage

use pocketmine\item\VanillaItems;

// Get item instances
$diamond = VanillaItems::DIAMOND();
$sword = VanillaItems::DIAMOND_SWORD();
$apple = VanillaItems::APPLE();
$arrow = VanillaItems::ARROW();

// Give items to players
$player->getInventory()->addItem(VanillaItems::DIAMOND()->setCount(64));

Common Items

Show Tools & Weapons

VanillaItems::DIAMOND_SWORD()
VanillaItems::DIAMOND_PICKAXE()
VanillaItems::DIAMOND_AXE()
VanillaItems::DIAMOND_SHOVEL()
VanillaItems::DIAMOND_HOE()
VanillaItems::BOW()
VanillaItems::ARROW()
VanillaItems::FISHING_ROD()
VanillaItems::SHEARS()

Show Armor

VanillaItems::DIAMOND_HELMET()
VanillaItems::DIAMOND_CHESTPLATE()
VanillaItems::DIAMOND_LEGGINGS()
VanillaItems::DIAMOND_BOOTS()
VanillaItems::IRON_HELMET()
VanillaItems::IRON_CHESTPLATE()
VanillaItems::IRON_LEGGINGS()
VanillaItems::IRON_BOOTS()

Show Food

VanillaItems::APPLE()
VanillaItems::BREAD()
VanillaItems::COOKED_BEEF()
VanillaItems::COOKED_CHICKEN()
VanillaItems::GOLDEN_APPLE()
VanillaItems::ENCHANTED_GOLDEN_APPLE()
VanillaItems::COOKIE()
VanillaItems::CAKE()

Show Materials

VanillaItems::DIAMOND()
VanillaItems::EMERALD()
VanillaItems::GOLD_INGOT()
VanillaItems::IRON_INGOT()
VanillaItems::COAL()
VanillaItems::REDSTONE_DUST()
VanillaItems::LAPIS_LAZULI()
VanillaItems::STICK()
VanillaItems::STRING()

Common Usage Patterns

Creating Custom Items

use pocketmine\item\VanillaItems;
use pocketmine\item\enchantment\EnchantmentInstance;
use pocketmine\item\enchantment\VanillaEnchantments;

public function createLegendarySword() : Item{
    $sword = VanillaItems::DIAMOND_SWORD();
    
    $sword->setCustomName("§6Excalibur");
    $sword->setLore([
        "§7A legendary blade",
        "§7forged by ancient smiths",
        "",
        "§9Sharpness X",
        "§9Unbreaking V"
    ]);
    
    $sword->addEnchantment(new EnchantmentInstance(VanillaEnchantments::SHARPNESS(), 10));
    $sword->addEnchantment(new EnchantmentInstance(VanillaEnchantments::UNBREAKING(), 5));
    
    // Add custom NBT
    $nbt = $sword->getNamedTag();
    $nbt->setString("ItemType", "legendary");
    $nbt->setInt("ItemLevel", 100);
    $sword->setNamedTag($nbt);
    
    return $sword;
}

Checking Item Data

use pocketmine\event\player\PlayerInteractEvent;

public function onInteract(PlayerInteractEvent $event) : void{
    $player = $event->getPlayer();
    $item = $event->getItem();
    
    // Check custom NBT
    $nbt = $item->getNamedTag();
    if($nbt->getTag("ItemType") !== null){
        $type = $nbt->getString("ItemType");
        if($type === "legendary"){
            $level = $nbt->getInt("ItemLevel", 1);
            $player->sendMessage("Legendary Item (Level $level)!");
        }
    }
}

Item Durability

use pocketmine\item\Durable;

if($item instanceof Durable){
    $damage = $item->getDamage();
    $maxDurability = $item->getMaxDurability();
    $remaining = $maxDurability - $damage;
    
    $player->sendMessage("Durability: $remaining / $maxDurability");
    
    // Damage the item
    $item->applyDamage(1);
}

Giving Items with Commands

use pocketmine\command\Command;
use pocketmine\command\CommandSender;
use pocketmine\player\Player;
use pocketmine\item\VanillaItems;

public function onCommand(CommandSender $sender, Command $command, string $label, array $args) : bool{
    if($command->getName() === "givekit"){
        if($sender instanceof Player){
            $sender->getInventory()->addItem(
                VanillaItems::DIAMOND_SWORD(),
                VanillaItems::DIAMOND_PICKAXE(),
                VanillaItems::DIAMOND_AXE(),
                VanillaItems::COOKED_BEEF()->setCount(64)
            );
            $sender->sendMessage("Kit received!");
            return true;
        }
    }
    return false;
}

Core API

World & Gameplay

Events

Utilities

Documentation Index

​Overview

​Item Class

​Core Methods

​getTypeId

​getStateId

​getName

​getVanillaName

​Count & Stack

​getCount

​setCount

​pop

​getMaxStackSize

​isNull

​Custom Name & Lore

​hasCustomName

​getCustomName

​setCustomName

​clearCustomName

​getLore

​setLore

​NBT Data

​hasNamedTag

​getNamedTag

​setNamedTag

​clearNamedTag

​Keep on Death

​keepOnDeath

​setKeepOnDeath

​Comparison

​equals

​canStackWith

​Block Interaction

​canBePlaced

​getBlock

​Combat & Tools

​getAttackPoints

​getDefensePoints

​getBlockToolType

​getBlockToolHarvestLevel

​getMiningEfficiency

​Actions & Events

​onInteractBlock

​onClickAir

​onReleaseUsing

​onDestroyBlock

​onAttackEntity

​Enchantments

​hasEnchantment

​getEnchantment

​addEnchantment

​removeEnchantment

​removeEnchantments

​getEnchantments

​Fuel & Fire Resistance

​getFuelTime

​getFuelResidue

​isFireProof

​Cooldowns

​getCooldownTicks

​getCooldownTag

​VanillaItems Helper

​Usage

​Common Items

​Common Usage Patterns

​Creating Custom Items

​Checking Item Data

​Item Durability

​Giving Items with Commands

Overview

Item Class

Core Methods

getTypeId

getStateId

getName

getVanillaName

Count & Stack

getCount

setCount

pop

getMaxStackSize

isNull

Custom Name & Lore

hasCustomName

getCustomName

setCustomName

clearCustomName

getLore

setLore

NBT Data

hasNamedTag

getNamedTag

setNamedTag

clearNamedTag

Keep on Death

keepOnDeath

setKeepOnDeath

Comparison

equals

canStackWith

Block Interaction

canBePlaced

getBlock

Combat & Tools

getAttackPoints

getDefensePoints

getBlockToolType

getBlockToolHarvestLevel

getMiningEfficiency

Actions & Events

onInteractBlock

onClickAir

onReleaseUsing

onDestroyBlock

onAttackEntity

Enchantments

hasEnchantment

getEnchantment

addEnchantment

removeEnchantment

removeEnchantments

getEnchantments

Fuel & Fire Resistance

getFuelTime

getFuelResidue

isFireProof

Cooldowns

getCooldownTicks

getCooldownTag

VanillaItems Helper

Usage

Common Items

Common Usage Patterns

Creating Custom Items

Checking Item Data

Item Durability

Giving Items with Commands