🎒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 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

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

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

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

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

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

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.

---