🎒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

• auto_feed

• enhance_equipment

• enhance_helditem

• replace_item

• shuffle_inventory

• change_item

• cost_price

• drop_item

• preserve_inventory

• preserve_item

• preserve_experience

• use_on

---

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.

---

auto_feed

Purpose: Finds and consumes the first eligible food item in a player's storage inventory through the NMS bridge.

Context: Default target: SOURCE; target must be a living online player with food below 20.

Fields

Field	Default	Description
threshold	10	Maximum food level at which auto-feeding may run.
health-not-full-threshold	threshold	Threshold used when current health is below maximum.
success-abilities	empty	Child abilities executed after successful consumption.

Example

type: auto_feed
target: SOURCE
threshold: 10
health-not-full-threshold: 16
success-abilities:
  sound:
    type: sound
    sound: ENTITY_GENERIC_EAT

Behavior and limits

• Scans storage slots in order and uses the first edible item or item with a food component.

• Requires NMS FINISH_USING_ITEM; container remainders are given or dropped.

• On failed NMS use, the removed food item is returned.

---

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.

---

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.

---

change_item

Purpose: Applies EnchantmentReform ChangesManager mutations to every selected matching item.

Context: Uses the extended item selector and optional equipment holder from the common ability item fields.

Fields

Field	Default	Description
item / item.selector	CONTEXT	Item selector; may select one or multiple equipment items.
item-holder / item.holder	default target	Holder selector for equipment items.
match-item	match all	MatchItemFormat filter.
changes	empty	ChangesManager mutations.

Example

type: change_item
item:
  selector: MAIN_HAND
  holder: SOURCE
match-item:
  material-tag:
    - minecraft:damageable
changes:
  damage:
    operation: SUBTRACT
    value: 2

Behavior and limits

• Every selected item is checked independently.

• The active-enchantment cache is cleared afterward so item changes are re-evaluated.

---

cost_price

Purpose: Checks and optionally charges a configured price, then executes success or failure child abilities.

Context: payer must resolve to a player; provider-backed prices require their integration.

Fields

Field	Default	Description
payer	PLAYER	Player selector used for affordability and payment.
cost / amount / price.cost	0	Required amount; first present location wins.
take / price.take	true	Whether to actually remove the price.
cost-every	1	Charge only every Nth activation; other activations run success children for free.
price	required	Price definition: hook item, vanilla item, MatchItemFormat, hook economy, vanilla economy, placeholder, reserve, or free.
abilities	required	Success child abilities.
else-abilities	empty	Failure branch; preferred fallback name.
failure-abilities / fail-abilities	empty	Additional failure aliases.

Example

type: cost_price
payer: PLAYER
cost: 10
take: true
price:
  economy-plugin: Vault
  economy-type: default
abilities:
  reward:
    type: potion_effect
    target: SOURCE
    potion: HASTE
    duration: 100
failure-abilities:
  message:
    type: send_message
    message: '<red>You cannot afford this ability.'

Behavior and limits

• Negative cost fails.

• When no payer resolves, the failure branch runs.

• Price detection is based on fields present in price; invalid configuration logs an error.

• The execution return value propagates from the chosen child branch.

---

drop_item

Purpose: Moves an amount from a selected existing item stack into a dropped item entity.

Context: Requires a selected item and resolved world location.

Fields

Field	Default	Description
item / item.selector	CONTEXT	Item selector from the common item-selection system.
item-holder / item.holder	default target	Equipment holder selector.
amount	entire stack	Amount removed and dropped, clamped to 1..available.
naturally	true	Use natural random drop motion instead of exact drop.
pickup-delay	unset	Optional pickup delay, minimum 0.

Example

type: drop_item
item:
  selector: MAIN_HAND
  holder: SOURCE
amount: 1
naturally: true
pickup-delay: 20

Behavior and limits

• This ability does not build a new ItemFormat item; it consumes from the selected stack.

• Invalid/empty selected items are skipped.

---

preserve_inventory

Purpose: Keeps inventory and/or experience through a player death event.

Context: Requires PlayerDeathEvent.

Fields

Field	Default	Description
inventory	true	Enable keep-inventory and clear event drops.
experience	true	Enable keep-level and set dropped experience result to zero.

Example

type: preserve_inventory
inventory: true
experience: true

Behavior and limits

• This directly edits the death event and should be tested with gamerules and other keep-inventory plugins.

---

preserve_item

Purpose: Preserves the current context item through player death.

Context: Requires player SOURCE, PlayerDeathEvent, and non-null context.item().

Fields

No type-specific fields.

Example

type: preserve_item

Behavior and limits

• A clone of the context item is removed from death drops by similarity and returned one tick later.

• Inventory overflow is dropped naturally at the player.

---

preserve_experience

Purpose: Preserves a percentage of the player's total experience through death.

Context: Requires player SOURCE and PlayerDeathEvent.

Fields

Field	Default	Description
ratio	0.5	Fraction retained, clamped to 0..1.

Example

type: preserve_experience
ratio: 0.75

Behavior and limits

• Retained experience is subtracted from the mutable dropped-experience result.

• The retained points are given back one tick later.

---

use_on

Purpose: Uses a hand or matched inventory item on a block through the NMS use-on bridge.

Context: Requires a player, supported hand, resolvable block, valid face, and NMS implementation.

Fields

Field	Default	Description
player	SOURCE	Player selector.
hand	CONTEXT	CONTEXT, trigger-item aliases, MAIN_HAND, or OFF_HAND.
block-offset.x/y/z	0	Relative offset from context/resolved block.
face	UP	Cardinal block face; TOP/BOTTOM aliases are supported.
hit.x/y/z	0.5	Hit coordinates inside block, clamped 0..1.
inside	false	Whether hit is considered inside the block.
inventory-items / inventory-item	unset	MatchItemFormat used to find a temporary inventory item to use.
success-abilities	empty	Children after successful NMS use.
failure-abilities	empty	Children after failure.

Example

type: use_on
player: SOURCE
hand: CONTEXT
face: UP
block-offset:
  y: -1
hit:
  x: 0.5
  y: 1
  z: 0.5
inventory-items:
  material:
    - BONE_MEAL
success-abilities:
  sound:
    type: sound
    sound: ITEM_BONE_MEAL_USE

Behavior and limits

• When matching an inventory item, it is temporarily moved into the selected hand and the remaining stack is restored to its slot.

• Only main/off hand are accepted.

• The chosen success/failure branch executes with resolved block context.

---