# Items

This page explains how to define custom items in **YAML format**.

***

## Example

```yaml
compressed_coal:
  type: coal
  amount: 1
  name: "&8Compressed Coal"
  lore:
    - "&7A dense chunk of coal, ready for use."
  model-data: 1003
  damage: 0
  repair-cost: 10
  flags:
    - hide enchants
  unbreakable: false
  enchants:
    smite: 1
  attributes:
    - knockback_resistance 0.2 operation=multiply slot=chest name=stability
```

***

## Basic Options

### `type`

* **Description:** The base Minecraft material.
* **Example:** `coal`, `diamond_sword`, `iron_ingot`.

### `amount`

* **Description:** Stack size of the item.
* **Default:** `1`

### `name`

* **Description:** Custom display name. Supports Minecraft color codes (`&`).
* **Example:** `&8Compressed Coal`

### `lore`

* **Description:** List of lore lines shown under the item name. Supports color codes.
* **Example:**

  ```yaml
  lore:
    - "&7A dense chunk of coal, ready for use."
  ```

### `model-data`

* **Description:** Custom model data value for use with resource packs.
* **Example:** `1003`

### `durability` 

* **Description:** The item’s durability damage.
* **Default:** `0`

### `max-durability` \[1.20.5+]

* Description: The item's maximum durability

### `repair-cost`

* **Description:** Repair cost in an anvil.
* **Example:** `10`

### `flags`

* **Description:** A list of ItemFlags [1.16.5-1.18.2](https://helpch.at/docs/1.16.5/org/bukkit/inventory/ItemFlag.html), [1.19.4-1.21.4](https://helpch.at/docs/1.21.4/org/bukkit/inventory/ItemFlag.html), [1.21.5+](https://helpch.at/docs/1.21.5/org/bukkit/inventory/ItemFlag.html)
* **Example:**

  ```yaml
  flags:
    - hide enchants
  ```

### `unbreakable`

* **Description:** Whether the item is unbreakable.
* **Default:** `false`

### `enchants`

* **Description:** A section of enchantments and their levels. [1.16.5-1.17.1](https://helpch.at/docs/1.16.5/org/bukkit/enchantments/Enchantment.html), [1.18-1.18.2](https://helpch.at/docs/1.18/org/bukkit/enchantments/Enchantment.html), [1.19-1.20.4](https://helpch.at/docs/1.19/org/bukkit/enchantments/Enchantment.html), [1.20.5+](https://helpch.at/docs/1.20.5/org/bukkit/enchantments/Enchantment.html)
* **Example:**

  ```yaml
  enchants:
    smite: 1
  ```

### `attributes`

* **Description:** List of custom attribute modifiers.
* **Format:**

  ```
  <attribute> <value> operation=<operation> slot=<slot> name=<uniqueName>
  ```
* **Operations:**

  ```
  ADD → Adds a flat value.
  PERCENT → Increments the base value.
  MULTIPLY → Multiplies the base value.
  ```
* **Example:**

  ```yaml
  attributes:
    - knockback_resistance 0.2 operation=multiply slot=chest name=stability
  ```

***

## Custom Options

### `unplaceable`

* **Description:** Whether the player should be able to place the item.

```yaml
unplaceable: true
```

### `max-uses`

* **Description:** The maximum uses the item should ever reach.

```yaml
max-uses: 100
```

### `uses`

* **Description:** The starting uses of an item

```yaml
uses: 70
```

### `on-block-break`

* **Description:** Triggered when a player breaks a block while holding this item

```yaml
on-block-break:
  if: toolHasUsesLeft   # default is 1
  do:
    - consumeToolUses   # default is 1
  else:
    - cancelEvent
    - sendChat &4Your tool is out of uses
```

### `on-swap`

* **Description:** Triggered when a player swaps item with off hand (presses F key)

### `on-drop`

* **Description:** Triggered when a player drops the item (presses Q key)

```yaml
on-drop:
  if-not: hasFlag confirm_drop
  do:
    - cancelEvent
    - giveTemporaryFlag confirm_drop duration=0.5s 
    - sendChat &4Press Q again to drop item
```

### `on-left-click`

* **Description:** Triggered when a player left-clicks a block or air while holding this item

### `on-right-click`

* **Description:** Triggered when a player right-clicks a block or air while holding this item

### `on-left-click-block`

* **Description:** Triggered when a player left-clicks a block while holding this item

### `on-left-click-air`

* **Description:** Triggered when a player left-clicks air while holding this item

### `on-right-click-block`

* **Description:** Triggered when a player right-clicks a block while holding this item

### `on-right-click-air`

* **Description:** Triggered when a player right-clicks air while holding this item


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://pigaut.gitbook.io/orestack/items.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.