Class ItemStack

Defines a collection of items.

Example

givePlayerIronFireSword.ts 

// Spawns a bunch of item stacks
import { EnchantmentType, ItemComponentTypes, ItemStack, Player } from '@minecraft/server';
import { MinecraftItemTypes, MinecraftEnchantmentTypes } from '@minecraft/vanilla-data';

function giveFireSword(player: Player) {
    const ironFireSword = new ItemStack(MinecraftItemTypes.DiamondSword, 1);

    const enchantments = ironFireSword?.getComponent(ItemComponentTypes.Enchantable);
    if (enchantments) {
        enchantments.addEnchantment({ type: new EnchantmentType(MinecraftEnchantmentTypes.FireAspect), level: 1 });
    }

    const inventory = player.getComponent('minecraft:inventory');
    if (inventory === undefined || inventory.container === undefined) {
        return;
    }
    inventory.container.setItem(0, ironFireSword);
}

Example

givePlayerEquipment.ts 

// Gives the player some equipment
import { EquipmentSlot, ItemStack, Player, EntityComponentTypes } from '@minecraft/server';
import { MinecraftItemTypes } from '@minecraft/vanilla-data';

function giveEquipment(player: Player) {
    const equipmentCompPlayer = player.getComponent(EntityComponentTypes.Equippable);
    if (equipmentCompPlayer) {
        equipmentCompPlayer.setEquipment(EquipmentSlot.Head, new ItemStack(MinecraftItemTypes.GoldenHelmet));
        equipmentCompPlayer.setEquipment(EquipmentSlot.Chest, new ItemStack(MinecraftItemTypes.IronChestplate));
        equipmentCompPlayer.setEquipment(EquipmentSlot.Legs, new ItemStack(MinecraftItemTypes.DiamondLeggings));
        equipmentCompPlayer.setEquipment(EquipmentSlot.Feet, new ItemStack(MinecraftItemTypes.NetheriteBoots));
        equipmentCompPlayer.setEquipment(EquipmentSlot.Mainhand, new ItemStack(MinecraftItemTypes.WoodenSword));
        equipmentCompPlayer.setEquipment(EquipmentSlot.Offhand, new ItemStack(MinecraftItemTypes.Shield));
    } else {
        console.warn('No equipment component found on player');
    }
}

Example

spawnFeatherItem.ts 

// Spawns a feather at a location
import { ItemStack, DimensionLocation } from '@minecraft/server';
import { MinecraftItemTypes } from '@minecraft/vanilla-data';

function spawnFeather(location: DimensionLocation) {
    const featherItem = new ItemStack(MinecraftItemTypes.Feather, 1);
    location.dimension.spawnItem(featherItem, location);
}

Hierarchy

  • ItemStack

Constructors

constructor

Properties

amount isStackable keepOnDeath lockMode maxAmount nameTag? type typeId

Methods

clearDynamicProperties clone getCanDestroy getCanPlaceOn getComponent getComponents getDynamicProperty getDynamicPropertyIds getDynamicPropertyTotalByteCount getLore getTags hasComponent hasTag isStackableWith matches setCanDestroy setCanPlaceOn setDynamicProperty setLore

Constructors

constructor

  • Parameters

    • itemType: string | ItemType

      Type of item to create. See the @minecraft/vanilla-data.MinecraftItemTypes enumeration for a list of standard item types in Minecraft experiences.

    • Optional amount: number

      Number of items to place in the stack, between 1-255. The provided value will be clamped to the item's maximum stack size. Note that certain items can only have one item in the stack.

      Optional

    Returns ItemStack

    Remarks

    Creates a new instance of a stack of items for use in the world.

    Throws

    Throws if itemType is invalid, or if amount is outside the range of 1-255.

Properties

amount

amount: number

Remarks

Number of the items in the stack. Valid values range between 1-255. The provided value will be clamped to the item's maximum stack size.

This property can't be edited in read-only mode.

Throws

Throws if the value is outside the range of 1-255.

Readonly isStackable

isStackable: boolean

Remarks

Returns whether the item is stackable. An item is considered stackable if the item's maximum stack size is greater than 1 and the item does not contain any custom data or properties.

keepOnDeath

keepOnDeath: boolean

Remarks

Gets or sets whether the item is kept on death.

This property can't be edited in read-only mode.

lockMode

lockMode: ItemLockMode

Remarks

Gets or sets the item's lock mode. The default value is ItemLockMode.none.

This property can't be edited in read-only mode.

Readonly maxAmount

maxAmount: number

Remarks

The maximum stack size. This value varies depending on the type of item. For example, torches have a maximum stack size of 64, while eggs have a maximum stack size of 16.

Optional nameTag

nameTag?: string

Remarks

Given name of this stack of items. The name tag is displayed when hovering over the item. Setting the name tag to an empty string or undefined will remove the name tag.

This property can't be edited in read-only mode.

Throws

Throws if the length exceeds 255 characters.

Readonly type

type: ItemType

Remarks

The type of the item.

Readonly typeId

typeId: string

Remarks

Identifier of the type of items for the stack. If a namespace is not specified, 'minecraft:' is assumed. Examples include 'wheat' or 'apple'.

Methods

clearDynamicProperties

  • Returns void

    Remarks

    Clears all dynamic properties that have been set on this item stack.

clone

  • Returns ItemStack

    Returns a copy of this item stack.

    Remarks

    Creates an exact copy of the item stack, including any custom data or properties.

getCanDestroy

  • Returns string[]

    Remarks

    Get the list of block types this item can break in Adventure mode.

    This function can't be called in read-only mode.

getCanPlaceOn

  • Returns string[]

    Remarks

    Get the list of block types this item can be placed on in Adventure mode.

    This function can't be called in read-only mode.

getComponent

  • Parameters

    • componentId: string

      The identifier of the component (e.g., 'minecraft:food'). If no namespace prefix is specified, 'minecraft:' is assumed. Available component IDs can be found as part of the ItemComponentTypes enum.

    Returns ItemComponent

    Returns the component if it exists on the item stack, otherwise undefined.

    Remarks

    Gets a component (that represents additional capabilities) for an item stack.

    Example

    durability.ts 

    // Gives a player a half-damaged diamond sword
    import { ItemStack, Player, ItemComponentTypes, EntityComponentTypes } from '@minecraft/server';
    import { MinecraftItemTypes } from '@minecraft/vanilla-data';

    function giveHurtDiamondSword(player: Player) {
        const hurtDiamondSword = new ItemStack(MinecraftItemTypes.DiamondSword);
        const durabilityComponent = hurtDiamondSword.getComponent(ItemComponentTypes.Durability);
        if (durabilityComponent !== undefined) {
            durabilityComponent.damage = durabilityComponent.maxDurability / 2;
        }

        const inventory = player.getComponent(EntityComponentTypes.Inventory);
        if (inventory === undefined || inventory.container === undefined) {
            return;
        }

        inventory.container.addItem(hurtDiamondSword);
    }

    Example

    getItemDurability.js 

    import { world } from "@minecraft/server";

    const player = world.getPlayers()[0];
    const inventory = player.getComponent("inventory");
    const slot = inventory.container.getSlot(player.selectedSlotIndex);
    let durabilityComp = slot.getItem().getComponent("durability");
    player.sendMessage(
        "Item Durability: " +
            (durabilityComp.maxDurability - durabilityComp.damage) +
            "/" +
            durabilityComp.maxDurability
    );

getComponents

  • Returns ItemComponent[]

    Remarks

    Returns all components that are both present on this item stack and supported by the API.

getDynamicProperty

  • Parameters

    • identifier: string

      The property identifier.

    Returns string | number | boolean | Vector3

    Returns the value for the property, or undefined if the property has not been set.

    Remarks

    Returns a property value.

getDynamicPropertyIds

  • Returns string[]

    A string array of the dynamic properties set on this entity.

    Remarks

    Returns the available set of dynamic property identifiers that have been used on this entity.

getDynamicPropertyTotalByteCount

  • Returns number

    Remarks

    Returns the total size, in bytes, of all the dynamic properties that are currently stored for this entity. This includes the size of both the key and the value. This can be useful for diagnosing performance warning signs - if, for example, an entity has many megabytes of associated dynamic properties, it may be slow to load on various devices.

getLore

  • Returns string[]

    An array of lore lines. If the item does not have lore, returns an empty array.

    Remarks

    Returns the lore value - a secondary display string - for an ItemStack.

getTags

  • Returns string[]

    Remarks

    Returns a set of tags associated with this item stack.

hasComponent

  • Parameters

    • componentId: string

      The identifier of the component (e.g., 'minecraft:food') to retrieve. If no namespace prefix is specified, 'minecraft:' is assumed.

    Returns boolean

    Remarks

    Returns true if the specified component is present on this item stack.

hasTag

  • Parameters

    • tag: string

      Tag to search for.

    Returns boolean

    True if the Item Stack has the tag associated with it, else false.

    Remarks

    Checks whether this item stack has a particular tag associated with it.

isStackableWith

  • Parameters

    • itemStack: ItemStack

      ItemStack to check stacking compatability with.

    Returns boolean

    True if the Item Stack is stackable with the itemStack passed in.

    Remarks

    Returns whether this item stack can be stacked with the given itemStack. This is determined by comparing the item type and any custom data and properties associated with the item stacks. The amount of each item stack is not taken into consideration.

matches

  • Parameters

    • itemName: string

      Identifier of the item.

    • Optional states: Record<string, string | number | boolean>

      Applicable only for blocks. An optional set of states to compare against. If states is not specified, matches checks against the set of types more broadly.

      Optional

    Returns boolean

    Returns a boolean whether the specified item matches.

    Remarks

    Version safe way of checking if an item matches.

    Example

    sameIronSword.js 

    import { ItemStack, world } from "@minecraft/server";

    const item1 = new ItemStack("minecraft:iron_sword", 1);
    item1.matches("minecraft:iron_sword");

    Example

    sameTrapdoor.js 

    import { ItemStack, world } from "@minecraft/server";

    const item1 = new ItemStack("minecraft:acacia_trapdoor", 1);
    item1.matches("minecraft:acacia_trapdoor", {
        direction: 0,
        open_bit: true,
        upside_down_bit: false,
    });

setCanDestroy

  • Parameters

    • Optional blockIdentifiers: string[]

      String list of block types that the item can destroy.

      Optional

    Returns void

    Remarks

    The list of block types this item can break in Adventure mode. The block names are displayed in the item's tooltip. Setting the value to undefined will clear the list.

    This function can't be called in read-only mode.

    Throws

    Throws if any of the provided block identifiers are invalid.

    Example

    example.ts 

    const specialPickaxe = new ItemStack('minecraft:diamond_pickaxe');
    specialPickaxe.setCanDestroy(['minecraft:cobblestone', 'minecraft:obsidian']);

    // Creates a diamond pickaxe that can destroy cobblestone and obsidian
    import { ItemStack, Player } from '@minecraft/server';
    import { MinecraftItemTypes } from '@minecraft/vanilla-data';

    function giveRestrictedPickaxe(player: Player) {
        const specialPickaxe = new ItemStack(MinecraftItemTypes.DiamondPickaxe);
        specialPickaxe.setCanPlaceOn([MinecraftItemTypes.Cobblestone, MinecraftItemTypes.Obsidian]);

        const inventory = player.getComponent('inventory');
        if (inventory === undefined || inventory.container === undefined) {
            return;
        }

        inventory.container.addItem(specialPickaxe);
    }

setCanPlaceOn

  • Parameters

    • Optional blockIdentifiers: string[]

      String list of block types that the item can be placed on.

      Optional

    Returns void

    Remarks

    The list of block types this item can be placed on in Adventure mode. This is only applicable to block items. The block names are displayed in the item's tooltip. Setting the value to undefined will clear the list.

    This function can't be called in read-only mode.

    Throws

    Throws if any of the provided block identifiers are invalid.

    Example

    example.ts 

    // Creates a gold block that can be placed on grass and dirt
    import { ItemStack, Player, EntityComponentTypes } from '@minecraft/server';
    import { MinecraftItemTypes } from '@minecraft/vanilla-data';

    function giveRestrictedGoldBlock(player: Player) {
        const specialGoldBlock = new ItemStack(MinecraftItemTypes.GoldBlock);
        specialGoldBlock.setCanPlaceOn([MinecraftItemTypes.Grass, MinecraftItemTypes.Dirt]);

        const inventory = player.getComponent(EntityComponentTypes.Inventory);
        if (inventory === undefined || inventory.container === undefined) {
            return;
        }

        inventory.container.addItem(specialGoldBlock);
    }

setDynamicProperty

  • Parameters

    • identifier: string

      The property identifier.

    • Optional value: string | number | boolean | Vector3

      Data value of the property to set.

      Optional

    Returns void

    Remarks

    Sets a specified property to a value. Note: This function only works with non-stackable items.

    Throws

    Throws if the item stack is stackable.

setLore

  • Parameters

    • Optional loreList: string[]

      List of lore lines. Each element in the list represents a new line. The maximum lore line count is 20. The maximum lore line length is 50 characters.

      Optional

    Returns void

    Remarks

    Sets the lore value - a secondary display string - for an ItemStack. The lore list is cleared if set to an empty string or undefined.

    This function can't be called in read-only mode.

    Throws

    This function can throw errors.

    Example

    diamondAwesomeSword.ts 

    import { EntityComponentTypes, ItemStack, Player } from '@minecraft/server';
    import { MinecraftItemTypes } from '@minecraft/vanilla-data';

    function giveAwesomeSword(player: Player) {
        const diamondAwesomeSword = new ItemStack(MinecraftItemTypes.DiamondSword, 1);
        diamondAwesomeSword.setLore([
            '§c§lDiamond Sword of Awesome§r',
             '+10 coolness', '§p+4 shiny§r'
        ]);

        // hover over/select the item in your inventory to see the lore.
        const inventory = player.getComponent(EntityComponentTypes.Inventory);
        if (inventory === undefined || inventory.container === undefined) {
            return;
        }

        inventory.container.setItem(0, diamondAwesomeSword);
    }

Settings

Member Visibility

Theme

On This Page