Item¶

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

Fields¶

type: ItemType — Read-Only¶

A reference to the specific type of the item (e.g., "sword", "pickaxe").

name: string — Read/Write¶

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

count: number — Read/Write¶

The quantity of the item in a stack.

maxCount: number — Read-Only¶

The maximum quantity of the item in a stack.

stackable: boolean — Read-Only¶

Indicates whether the item can be stacked.

maxDamage: number — Read-Only¶

The maximum durability value this item can have before breaking.

damage: number — Read/Write¶

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

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

Methods¶

new(id: string, nbt: table|nil) → 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

Name	Type	Description
`id`	`string`	The item type identifier (e.g., "diamond_sword", "torch").
`nbt`	`table`\|`nil`	Optional 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.

putNbt(nbt: table)¶

Merges the given NBT data into this item's existing NBT.

This updates properties like the custom name, enchantments, or other item components.

Example

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

Parameters

Name	Type	Description
`nbt`	`table`	The NBT data to merge into this item.

copy() → item: Item¶

Creates a copy of this item.

Example

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

Returns

Item — item A new copy of this item.