> For the complete documentation index, see [llms.txt](https://enchantedmobs.superiormc.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://enchantedmobs.superiormc.cn/configs/info-of-abilities/inventory-equipment.md).

# Inventory and Equipment Abilities

Every registered ability on this page is documented as a complete reference entry. All entries also support the common ability fields from the [Abilities](/configs/info-of-abilities.md) page.

## Registry keys on this page

* `consume_food`
* `enhance_equipment`
* `enhance_helditem`
* `replace_item`
* `disarm`
* `shuffle_inventory`

***

## `consume_food`

**Purpose:** Consumes player saturation and/or food, including fractional food accumulation.

**Context:** Default `target`: `TARGET`; selected entity must be a player.

### Fields

| Field               | Default | Description                                            |
| ------------------- | ------- | ------------------------------------------------------ |
| `amount`            | `0.25`  | Combined amount; supports `{food}` and `{saturation}`. |
| `saturation-first`  | `true`  | Consume saturation before food in combined mode.       |
| `saturation-amount` | unset   | Explicit saturation consumption.                       |
| `food-amount`       | unset   | Explicit food consumption.                             |

### Example

```yaml
type: consume_food
target: TARGET
amount: 1.5
saturation-first: true
```

### Behavior and limits

* Fractional food consumption is stored per player until it reaches a whole point.
* When either explicit amount exists, explicit mode controls actual reductions.

***

## `enhance_equipment`

**Purpose:** Replaces selected armor pieces with newly created armor and random compatible enchantments.

**Context:** Default `target`: `SOURCE`; requires a living entity with equipment.

### Fields

| Field                  | Default        | Description                                              |
| ---------------------- | -------------- | -------------------------------------------------------- |
| `armor-material`       | `NETHERITE`    | Material prefix combined with armor piece names.         |
| `pieces`               | all armor      | List of `HELMET`, `CHESTPLATE`, `LEGGINGS`, and `BOOTS`. |
| `enchant.min-amount`   | `1`            | Minimum distinct enchantments.                           |
| `enchant.max-amount`   | `3`            | Maximum distinct enchantments.                           |
| `enchant.min-level`    | `1`            | Minimum level.                                           |
| `enchant.max-level`    | `4`            | Maximum level, capped by enchantment max.                |
| `enchant.enchantments` | all compatible | Optional allow-list of Bukkit enchantments.              |

### Example

```yaml
type: enhance_equipment
target: SOURCE
armor-material: DIAMOND
pieces:
  - HELMET
  - CHESTPLATE
enchant:
  min-amount: 1
  max-amount: 2
  min-level: 1
  max-level: 3
  enchantments:
    - PROTECTION
    - UNBREAKING
```

### Behavior and limits

* Existing selected equipment is replaced.
* Non-player equipment drop chances for replaced pieces are set to zero.

***

## `enhance_helditem`

**Purpose:** Adds random compatible enchantments to a held item.

**Context:** Default `target`: `SOURCE`; requires a living entity with equipment and a non-air hand item.

### Fields

| Field                | Default     | Description                                   |
| -------------------- | ----------- | --------------------------------------------- |
| `hand`               | `MAIN_HAND` | `MAIN_HAND` or `OFF_HAND`.                    |
| `enchant.min-amount` | `1`         | Minimum distinct enchantments.                |
| `enchant.max-amount` | `3`         | Maximum distinct enchantments.                |
| `enchant.min-level`  | `1`         | Minimum level.                                |
| `enchant.max-level`  | `4`         | Maximum level, capped by enchantment maximum. |

### Example

```yaml
type: enhance_helditem
target: SOURCE
hand: MAIN_HAND
enchant:
  min-amount: 1
  max-amount: 3
  min-level: 1
  max-level: 4
```

### Behavior and limits

* Compatible enchantments are selected without duplicates.
* For non-player equipment, both hand drop chances are set to zero.

***

## `replace_item`

**Purpose:** Builds an item from nested ItemFormat and places it in an equipment slot.

**Context:** Default `target`: `SOURCE`; requires a living entity with equipment.

### Fields

| Field  | Default     | Description                                                              |
| ------ | ----------- | ------------------------------------------------------------------------ |
| `slot` | `MAIN_HAND` | `MAIN_HAND`, `OFF_HAND`, `HELMET`, `CHESTPLATE`, `LEGGINGS`, or `BOOTS`. |
| `item` | required    | Nested ItemFormat used to build the replacement.                         |

### Example

```yaml
type: replace_item
target: SOURCE
slot: MAIN_HAND
item:
  material: DIAMOND_SWORD
  name: '<red>Elite Blade'
```

### Behavior and limits

* Non-player drop chance for the replaced slot is set to zero.
* Unsupported slot values do not change equipment.

***

## `disarm`

**Purpose:** Removes a matched main-hand or off-hand item and optionally drops it.

**Context:** Default `target`: `TARGET`; requires a living entity.

### Fields

| Field          | Default     | Description                                |
| -------------- | ----------- | ------------------------------------------ |
| `slot`         | `MAIN_HAND` | `MAIN_HAND` or `OFF_HAND`.                 |
| `match-item`   | match all   | Optional Match Item rules.                 |
| `drop`         | `true`      | For player targets, drop the removed item. |
| `pickup-delay` | `20`        | Pickup delay for the dropped item.         |

### Example

```yaml
type: disarm
target: TARGET
slot: MAIN_HAND
drop: true
pickup-delay: 40
match-item:
  material:
    - SHIELD
    - BOW
```

### Behavior and limits

* For non-player targets the item is removed but not dropped.
* Dropped player items are marked for the plugin's optional automatic-return behavior.

***

## `shuffle_inventory`

**Purpose:** Randomly permutes occupied player inventory slots inside a configured range.

**Context:** Default `target`: `TARGET`; selected entity must be a player.

### Fields

| Field        | Default | Description                              |
| ------------ | ------- | ---------------------------------------- |
| `start-slot` | `0`     | First player-inventory index, minimum 0. |
| `end-slot`   | `35`    | Last index, capped by inventory size.    |

### Example

```yaml
type: shuffle_inventory
target: TARGET
start-slot: 0
end-slot: 35
```

### Behavior and limits

* Only occupied slots participate, so empty slots stay empty.
* Fewer than two occupied slots produces no change.

***