# item

you can make custom item stacks using `Katton.item(...)` and manipulate their display names, lore, custom tags, enchantments, or clone them

---

## properties

```csharp
item.setName(text) //sets the custom display name of the item stack
```

## methods

```csharp
item.setLore(lines)
item.setTag(key, value)
item.getTag(key)
item.enchant(name, level)
item.clone()
item.dye(r,g,b)
```

---

### `setLore`

sets the lore description lines on the item stack

```csharp
item.setLore(lines)
```

| parameter | default | description |
| --- | --- | --- |
| `lines` | *required* | a list of string lines, supports `&` color codes |

#### example

```csharp
wand.setLore(["&7Right click to leap forward!", "&7Cooldown: none"])
```

---

### `setTag`

applies custom data stored directly on the item's metadata

```csharp
item.setTag(key, value)
```

| parameter | default | description |
| --- | --- | --- |
| `key` | *required* | custom tag key identifier string |
| `value` | *required* | string data value to attach |

> [!note]
> tag values are always stored and read back as strings

#### example

```csharp
val wand = Katton.item("stick")
wand.setName("&aLeap Wand")
wand.setTag("ability", "leap_wand") // mark this specific item
sender.give(wand)
```

---

### `getTag`

reads custom data stored directly on the item's metadata

```csharp
item.getTag(key)
```

| parameter | default | description |
| --- | --- | --- |
| `key` | *required* | custom tag key identifier string |

> [!note]
> `getTag` returns `null` if the tag was never set on that item

#### example

```csharp
@Katton.listen("player_rightclick")
function onLeap(event) {
    val item = event.item
    if (item != null && item.getTag("ability") == "leap_wand") { // this is one of our wands, not a random item
        event.player.launchForward(1.8, 0.65)
    }
}
```

---

### `enchant`

applies a vanilla enchantment to the item stack

```csharp
item.enchant(name, level)
```

| parameter | default | description |
| --- | --- | --- |
| `name` | *required* | enchantment string (e.g. `"sharpness"`, `"unbreaking"`) |
| `level` | *required* | enchantment level integer (clamped between `1` and `5`) |

> [!note]
> passing an unknown enchantment name throws a runtime error

#### example

```csharp
val sword = Katton.item("diamond_sword")
sword.enchant("sharpness", 5)
sword.enchant("unbreaking", 3)
```

---

### `clone`

creates a duplicate copy of the item stack with all its current properties and custom tags preserved

```csharp
item.clone()
```

#### example

```csharp
val original = Katton.item("stick")
original.setName("&aOriginal")
val copy = original.clone()
copy.setName("&bCopy")
```

---

### `dye`

dyes a leather armor item

```csharp
item.dye(r,g,b)
```

| parameter | default | description |
| --- | --- | --- |
| `r` | *required* | red color component (0 to 255) |
| `g` | *required* | green color component (0 to 255) |
| `b` | *required* | blue color component (0 to 255) |

#### example

```csharp
val leather = Katton.item("leather_chestplate")
leather.dye(245, 73, 39)
```

---
