Class: ItemStack

Defined in: @minecraft/server/index.d.ts:14511

Defines a collection of items.

Examples

itemStacks.ts

typescript

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

function itemStacks(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  const oneItemLoc = { x: targetLocation.x + targetLocation.y + 3, y: 2, z: targetLocation.z + 1 };
  const fiveItemsLoc = { x: targetLocation.x + 1, y: targetLocation.y + 2, z: targetLocation.z + 1 };
  const diamondPickaxeLoc = { x: targetLocation.x + 2, y: targetLocation.y + 2, z: targetLocation.z + 4 };

  const oneEmerald = new ItemStack(MinecraftItemTypes.Emerald, 1);
  const onePickaxe = new ItemStack(MinecraftItemTypes.DiamondPickaxe, 1);
  const fiveEmeralds = new ItemStack(MinecraftItemTypes.Emerald, 5);

  log(`Spawning an emerald at (${oneItemLoc.x}, ${oneItemLoc.y}, ${oneItemLoc.z})`);
  targetLocation.dimension.spawnItem(oneEmerald, oneItemLoc);

  log(`Spawning five emeralds at (${fiveItemsLoc.x}, ${fiveItemsLoc.y}, ${fiveItemsLoc.z})`);
  targetLocation.dimension.spawnItem(fiveEmeralds, fiveItemsLoc);

  log(`Spawning a diamond pickaxe at (${diamondPickaxeLoc.x}, ${diamondPickaxeLoc.y}, ${diamondPickaxeLoc.z})`);
  targetLocation.dimension.spawnItem(onePickaxe, diamondPickaxeLoc);
}

givePlayerEquipment.ts

typescript

import {
  world,
  ItemStack,
  EntityEquippableComponent,
  EquipmentSlot,
  EntityComponentTypes,
  DimensionLocation,
} from '@minecraft/server';
import { MinecraftItemTypes } from '@minecraft/vanilla-data';

function givePlayerEquipment(targetLocation: DimensionLocation) {
  const players = world.getAllPlayers();

  const armorStandLoc = { x: targetLocation.x, y: targetLocation.y, z: targetLocation.z + 4 };
  const armorStand = players[0].dimension.spawnEntity(MinecraftItemTypes.ArmorStand, armorStandLoc);

  const equipmentCompPlayer = players[0].getComponent(EntityComponentTypes.Equippable) as EntityEquippableComponent;
  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));
  }

  const equipmentCompArmorStand = armorStand.getComponent(EntityComponentTypes.Equippable) as EntityEquippableComponent;
  if (equipmentCompArmorStand) {
    equipmentCompArmorStand.setEquipment(EquipmentSlot.Head, new ItemStack(MinecraftItemTypes.GoldenHelmet));
    equipmentCompArmorStand.setEquipment(EquipmentSlot.Chest, new ItemStack(MinecraftItemTypes.IronChestplate));
    equipmentCompArmorStand.setEquipment(EquipmentSlot.Legs, new ItemStack(MinecraftItemTypes.DiamondLeggings));
    equipmentCompArmorStand.setEquipment(EquipmentSlot.Feet, new ItemStack(MinecraftItemTypes.NetheriteBoots));
    equipmentCompArmorStand.setEquipment(EquipmentSlot.Mainhand, new ItemStack(MinecraftItemTypes.WoodenSword));
    equipmentCompArmorStand.setEquipment(EquipmentSlot.Offhand, new ItemStack(MinecraftItemTypes.Shield));
  }
}

spawnFeatherItem.ts

typescript

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

function spawnFeatherItem(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  const featherItem = new ItemStack(MinecraftItemTypes.Feather, 1);

  targetLocation.dimension.spawnItem(featherItem, targetLocation);
  log(`New feather created at ${targetLocation.x}, ${targetLocation.y}, ${targetLocation.z}!`);
}

Constructors

Constructor

new ItemStack(itemType, amount?): ItemStack

Defined in: @minecraft/server/index.d.ts:14623

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.

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. Defaults to: 1 Bounds: [1, 255]

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

Defined in: @minecraft/server/index.d.ts:14524

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 restricted-execution mode.

Bounds: [1, 255]

Throws

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

isStackable

readonly isStackable: boolean

Defined in: @minecraft/server/index.d.ts:14532

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

Defined in: @minecraft/server/index.d.ts:14540

Remarks

Gets or sets whether the item is kept on death.

This property can't be edited in restricted-execution mode.

localizationKey

readonly localizationKey: string

Defined in: @minecraft/server/index.d.ts:14550

Remarks

Key for the localization of this items's name used in .lang files.

Throws

This property can throw when used.

minecraftcommon.EngineError

lockMode

lockMode: ItemLockMode

Defined in: @minecraft/server/index.d.ts:14559

Remarks

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

This property can't be edited in restricted-execution mode.

maxAmount

readonly maxAmount: number

Defined in: @minecraft/server/index.d.ts:14567

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.

nameTag?

optional nameTag?: string

Defined in: @minecraft/server/index.d.ts:14579

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 restricted-execution mode.

Throws

Throws if the length exceeds 255 characters.

type

readonly type: ItemType

Defined in: @minecraft/server/index.d.ts:14585

Remarks

The type of the item.

typeId

readonly typeId: string

Defined in: @minecraft/server/index.d.ts:14593

Remarks

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

weight

readonly weight: number

Defined in: @minecraft/server/index.d.ts:14602

Remarks

The total weight of all items in the stack plus the weight of all items in the items container which is defined with the Storage Item component. The weight per item can be modified by the Storage Weight Modifier component.

Methods

clearDynamicProperties()

clearDynamicProperties(): void

Defined in: @minecraft/server/index.d.ts:14630

Returns

void

Remarks

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

clone()

clone(): ItemStack

Defined in: @minecraft/server/index.d.ts:14639

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()

getCanDestroy(): string[]

Defined in: @minecraft/server/index.d.ts:14648

Returns

string[]

Remarks

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

This function can't be called in restricted-execution mode.

getCanPlaceOn()

getCanPlaceOn(): string[]

Defined in: @minecraft/server/index.d.ts:14657

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 restricted-execution mode.

getComponent()

getComponent<T>(componentId): ItemComponentReturnType<T> | undefined

Defined in: @minecraft/server/index.d.ts:14703

Type Parameters

T

T extends string

Parameters

componentId

T

The identifier of the component (e.g., 'minecraft:food'). If no namespace prefix is specified, 'minecraft:' is assumed. Available component IDs are those in the ItemComponentTypes enum and custom component IDs registered with the ItemComponentRegistry.

Returns

ItemComponentReturnType<T> | undefined

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

giveHurtDiamondSword.ts

typescript

import {
  world,
  ItemStack,
  EntityInventoryComponent,
  EntityComponentTypes,
  ItemComponentTypes,
  ItemDurabilityComponent,
  DimensionLocation,
} from '@minecraft/server';
import { MinecraftItemTypes } from '@minecraft/vanilla-data';

function giveHurtDiamondSword(targetLocation: DimensionLocation) {
  const hurtDiamondSword = new ItemStack(MinecraftItemTypes.DiamondSword);

  const durabilityComponent = hurtDiamondSword.getComponent(ItemComponentTypes.Durability) as ItemDurabilityComponent;

  if (durabilityComponent !== undefined) {
    durabilityComponent.damage = durabilityComponent.maxDurability / 2;
  }

  for (const player of world.getAllPlayers()) {
    const inventory = player.getComponent(EntityComponentTypes.Inventory) as EntityInventoryComponent;
    if (inventory && inventory.container) {
      inventory.container.addItem(hurtDiamondSword);
    }
  }
}

getComponents()

getComponents(): ItemComponent[]

Defined in: @minecraft/server/index.d.ts:14710

Returns

ItemComponent[]

Remarks

Returns all scripting components that are present on this item stack.

getDynamicProperty()

getDynamicProperty(identifier): string | number | boolean | Vector3 | undefined

Defined in: @minecraft/server/index.d.ts:14721

Parameters

identifier

string

The property identifier.

Returns

string | number | boolean | Vector3 | undefined

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

Remarks

Returns a property value.

getDynamicPropertyIds()

getDynamicPropertyIds(): string[]

Defined in: @minecraft/server/index.d.ts:14730

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()

getDynamicPropertyTotalByteCount(): number

Defined in: @minecraft/server/index.d.ts:14741

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()

getLore(): string[]

Defined in: @minecraft/server/index.d.ts:14751

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.

getRawLore()

getRawLore(): RawMessage[]

Defined in: @minecraft/server/index.d.ts:14762

Returns

RawMessage[]

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. String lore lines will be converted to a RawMessage and put under RawMessage.text.

getTags()

getTags(): string[]

Defined in: @minecraft/server/index.d.ts:14768

Returns

string[]

Remarks

Returns a set of tags associated with this item stack.

hasComponent()

hasComponent(componentId): boolean

Defined in: @minecraft/server/index.d.ts:14779

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()

hasTag(tag): boolean

Defined in: @minecraft/server/index.d.ts:14791

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()

isStackableWith(itemStack): boolean

Defined in: @minecraft/server/index.d.ts:14807

Parameters

itemStack

ItemStack

ItemStack to check stacking compatibility with.

Returns

boolean

True if the Item Stack is stackable with the itemStack passed in. False for non-stackable items.

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, but for non-stackable items this will always return false.

matches()

matches(itemName, states?): boolean

Defined in: @minecraft/server/index.d.ts:14821

Parameters

itemName

string

Identifier of the item.

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.

Returns

boolean

Returns a boolean whether the specified item matches.

Remarks

Version safe way of checking if an item matches.

setCanDestroy()

setCanDestroy(blockIdentifiers?): void

Defined in: @minecraft/server/index.d.ts:14854

Parameters

blockIdentifiers?

string[]

String list of block types that the item can destroy.

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 restricted-execution mode.

Throws

Throws if any of the provided block identifiers are invalid.

Example

giveDestroyRestrictedPickaxe.ts

typescript

import { world, ItemStack, EntityInventoryComponent, DimensionLocation } from '@minecraft/server';
import { MinecraftItemTypes } from '@minecraft/vanilla-data';

function giveDestroyRestrictedPickaxe(targetLocation: DimensionLocation) {
  for (const player of world.getAllPlayers()) {
    const specialPickaxe = new ItemStack(MinecraftItemTypes.DiamondPickaxe);
    specialPickaxe.setCanDestroy([MinecraftItemTypes.Cobblestone, MinecraftItemTypes.Obsidian]);

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

    inventory.container.addItem(specialPickaxe);
  }
}

setCanPlaceOn()

setCanPlaceOn(blockIdentifiers?): void

Defined in: @minecraft/server/index.d.ts:14888

Parameters

blockIdentifiers?

string[]

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

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 restricted-execution mode.

Throws

Throws if any of the provided block identifiers are invalid.

Example

givePlaceRestrictedGoldBlock.ts

typescript

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

function givePlaceRestrictedGoldBlock(targetLocation: DimensionLocation) {
  for (const player of world.getAllPlayers()) {
    const specialGoldBlock = new ItemStack(MinecraftItemTypes.GoldBlock);
    specialGoldBlock.setCanPlaceOn([MinecraftItemTypes.GrassBlock, MinecraftItemTypes.Dirt]);

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

    inventory.container.addItem(specialGoldBlock);
  }
}

setDynamicProperties()

setDynamicProperties(values): void

Defined in: @minecraft/server/index.d.ts:14903

Parameters

values

Record<string, boolean | number | string | Vector3 | undefined>

A Record of key value pairs of the dynamic properties to set. If the data value is null, it will remove that property instead.

Returns

void

Remarks

Sets multiple dynamic properties with specific values.

Throws

This function can throw errors.

minecraftcommon.ArgumentOutOfBoundsError

minecraftcommon.UnsupportedFunctionalityError

setDynamicProperty()

setDynamicProperty(identifier, value?): void

Defined in: @minecraft/server/index.d.ts:14921

Parameters

identifier

string

The property identifier.

value?

string | number | boolean | Vector3

Data value of the property to set. If the value is null, it will remove the property instead.

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.

minecraftcommon.ArgumentOutOfBoundsError

minecraftcommon.UnsupportedFunctionalityError

setLore()

setLore(loreList?): void

Defined in: @minecraft/server/index.d.ts:14958

Parameters

loreList?

(string | RawMessage)[]

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.

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 restricted-execution mode.

Throws

This function can throw errors.

minecraftcommon.ArgumentOutOfBoundsError

Error

Example

diamondAwesomeSword.ts

typescript

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);
}

Class: ItemStack ​

Examples ​

Constructors ​

Constructor ​

Parameters ​

itemType ​

amount? ​

Returns ​

Remarks ​

Throws ​

Properties ​

amount ​

Remarks ​

Throws ​

isStackable ​

Remarks ​

keepOnDeath ​

Remarks ​

localizationKey ​

Remarks ​

Throws ​

lockMode ​

Remarks ​

maxAmount ​

Remarks ​

nameTag? ​

Remarks ​

Throws ​

type ​

Remarks ​

typeId ​

Remarks ​

weight ​

Remarks ​

Methods ​

clearDynamicProperties() ​

Returns ​

Remarks ​

clone() ​

Returns ​

Remarks ​

getCanDestroy() ​

Returns ​

Remarks ​

getCanPlaceOn() ​

Returns ​

Remarks ​

getComponent() ​

Type Parameters ​

T ​

Parameters ​

componentId ​

Returns ​

Remarks ​

Example ​

getComponents() ​

Returns ​

Remarks ​

getDynamicProperty() ​

Parameters ​

identifier ​

Returns ​

Remarks ​

getDynamicPropertyIds() ​

Returns ​

Remarks ​

getDynamicPropertyTotalByteCount() ​

Returns ​

Remarks ​

getLore() ​

Returns ​

Remarks ​

getRawLore() ​

Returns ​

Remarks ​

getTags() ​

Returns ​

Remarks ​

hasComponent() ​

Parameters ​

Class: ItemStack

Examples

Constructors

Constructor

Parameters

itemType

amount?

Returns

Remarks

Throws

Properties

amount

Remarks

Throws

isStackable

Remarks

keepOnDeath

Remarks

localizationKey

Remarks

Throws

lockMode

Remarks

maxAmount

Remarks

nameTag?

Remarks

Throws

type

Remarks

typeId

Remarks

weight

Remarks

Methods

clearDynamicProperties()

Returns

Remarks

clone()

Returns

Remarks

getCanDestroy()

Returns

Remarks

getCanPlaceOn()

Returns

Remarks

getComponent()

Type Parameters

T

Parameters

componentId

Returns

Remarks

Example

getComponents()

Returns

Remarks

getDynamicProperty()

Parameters

identifier

Returns

Remarks

getDynamicPropertyIds()

Returns

Remarks

getDynamicPropertyTotalByteCount()

Returns

Remarks

getLore()

Returns

Remarks

getRawLore()

Returns

Remarks

getTags()

Returns

Remarks

hasComponent()

Parameters