# Item

One item stack, live. Handles come from `e:held_item()`, `e:equipped(slot)`,
[`inventory.item`](inventory.md), [`game.item(id)`](game.md) and similar. A handle for an
inventory slot tracks whatever sits in that slot now.

| Method | Returns |
|--------|---------|
| `id()`, `name()`, `count()` | Item id (`"minecraft:diamond_sword"`), display name, stack size |
| `empty()` | `true` for an empty slot |
| `max_count()`, `stackable()` | Maximum stack size, and whether it stacks at all |
| `rarity()` | `"common"`, `"uncommon"`, `"rare"`, `"epic"` |
| `use_action()` | `"none"`, `"eat"`, `"drink"`, `"block"`, `"bow"`, `"spear"`, … |
| `damage()`, `max_damage()` | Durability used and maximum (`0` when not damageable) |
| `damageable()`, `damaged()`, `unbreakable()` | Durability flags |
| `enchanted()` | `true` when it carries any enchantment |
| `enchantments()` | `id -> level`, e.g. `item:enchantments()["minecraft:sharpness"] == 5` |
| `custom_name()` | Anvil name, or `nil` |
| `tags()` | Item tag ids, e.g. `"minecraft:swords"` |
| `food()` | `{nutrition, saturation, can_always_eat}`, or `nil` |
| `attribute_modifiers()` | `{attribute, id, value, operation, slot}[]`, or `nil` |

## Text

These return [text](text.md) snapshots:

| Method | Returns |
|--------|---------|
| `name_text()`, `display_name()` | Display name |
| `item_name()`, `formatted_name()` | Base name, and the rarity-colored name |
| `custom_name_text()` | Anvil name, or `nil` |
| `hover_text()` | Bracketed chat name, `[Diamond Sword]` with a show-item hover |
| `lore()` | Lore lines, or `nil` |
| `tooltip([advanced])` | Tooltip lines exactly as the inventory renders them |

## Data components

| Method | Returns |
|--------|---------|
| `has_component(id)` | `true` when the stack carries it |
| `component(id)` | Decoded Lua value, `true` when present but not decodable, `nil` when absent |

```lua
local held = player:held_item()

if held:enchantments()["minecraft:sharpness"] then
    print(held:name() .. " has Sharpness")
end

if held:has_component("minecraft:piercing_weapon") then
    local weapon = held:component("minecraft:piercing_weapon")
    print(held:name() .. " dismounts: " .. tostring(weapon.dismounts))
end
```