Item¶

Represents an in-game item, including information about its type, name, quantity, durability, and metadata.

Fields¶

count: number — Read/Write¶

The quantity of the item in a stack.

damage: number — Read/Write¶

The current damage value, representing how worn or used the item is.

maxCount: number — Read-Only¶

The maximum quantity of the item in a stack.

maxDamage: number — Read-Only¶

The maximum durability value this item can have before breaking.

name: string — Read/Write¶

The name of the item, typically a human-readable label.

nbt: table — Read/Write¶

A copy of the NBT (Named Binary Tag) data attached to the item, including custom components and metadata. Changes made to this table do not affect the actual item until reassigned.

To modify the NBT effectively, use one of the following methods:

Retrieve a copy, modify it, then reassign:

local copy = item.nbt
copy.count = copy.count + 1
item.nbt = copy

Use putNbt(...) to merge changes:
```
item:putNbt({ count = 20 })
```

To remove single values, use removeNbt(...).

Components use the syntax of this Minecraft version: names are text component tables ({ text = "Blade" }) and enchantments map ids to levels ({ sharpness = 5 }). Values in the syntax of Minecraft 1.21.4 and earlier, such as JSON-string names or { levels = { sharpness = 5 } }, are taken literally or dropped, without an error.

stackable: boolean — Read-Only¶

Indicates whether the item can be stacked.

type: ItemType — Read-Only¶

A reference to the specific type of the item (e.g., "diamond_sword", "iron_pickaxe").

Methods¶

new(id: string, nbt?: table) → item: Item¶

Creates a new item with the specified ID and optional NBT data.

Example

local item = Item:new("diamond_sword", {
  components = {
    custom_name = {
      text = "Radiant Diamond Sword",
      color = "aqua",
      bold = true,
      italic = false
    },
    lore = {
      { text = "A diamond sword shimmering with energy", color = "gold", bold = true }
    }
  }
})

Parameters

id: string — The item type identifier (e.g., "diamond_sword", "torch").
nbt?: table — NBT data for customizing the item’s appearance or behavior.

Returns

item: Item — A new item instance with the specified type and optional NBT data.

copy() → item: Item¶

Creates a copy of this item.

Example

local item = spell.owner.mainHandItem:copy()
spell.owner.inventory.slots[40] = item

Returns

item: Item — A new copy of this item.

putNbt(nbtOrPath: table|string, value?: any) → changed: integer?¶

Merges NBT data into this item. There are two forms:

putNbt(nbt) merges the table into the item's NBT. This updates properties like the custom name, enchantments, or other item components.
putNbt(path, value) merges value at every tag the NBT path matches, with the same rules, and returns the number of changed tags. See Entity:putNbt for the path syntax. Component keys in a path are namespaced, e.g. components.minecraft:custom_name.

Example

item:putNbt({
  components = {
    enchantments = {
      sharpness = 5,
      unbreaking = 3
    }
  }
})
item:putNbt("count", 16)

Parameters

nbtOrPath: table|string — The NBT data to merge, or an NBT path.
value?: any — The value to merge at the path. Required when nbtOrPath is a path.

Returns

changed: integer? — The number of changed tags if a path was given, otherwise nil.

removeNbt(path: string, ...: string) → removed: integer¶

Removes every tag the given NBT paths match and returns how many were removed. See Entity:putNbt for the path syntax. Component keys are namespaced.

Only components stored on the item can be removed this way. A default component of the item type, such as the food of an apple, is not stored and cannot be removed.

Example

item:removeNbt("components.minecraft:custom_name")

Parameters

path: string — An NBT path.
...: string — More NBT paths.

Returns

removed: integer — The number of removed tags.