Using items

Charges

Field	Type	Default	Meaning
`use_mode`	enum	from `type`	`single_use`, `multiple` or `infinite`.
`uses`	integer	number of use clips, at least `1`	Charges (max durability) for `multiple`.
`use_order`	enum	`sequential`	`sequential` or `random`.
`consume_tick`	ticks or `"end"`	`"end"`	When the use commits. See below.
`consume_in_creative`	boolean	`false`	Spend charges and give result items in creative mode too.
`result_item`	resource location	none	Item given back when a charge is spent, like an empty bottle. Not given by `infinite` items.
`result_count`	integer	`1`	How many result items.

Mode	What a use does
`single_use`	Takes one item from the stack.
`multiple`	The item doesn’t stack, shows a durability bar, and breaks once `uses` charges are spent. With only one charge it’s treated as `single_use`.
`infinite`	Spends nothing.

use_order: "sequential" spreads the use clips across the charges, so it needs multiple. random picks a clip each use and works in any mode.

Committing a use

A use commits at consume_tick. The server handles it, and at that point it:

counts the vanilla item-used statistic and consume-item advancement trigger,
spends the charge,
gives the result_item,
starts the cooldown.

If the stack is now empty, the result item goes into the hand. Otherwise it goes to the inventory, or drops if the inventory is full. In creative mode the use is still counted, but nothing is spent or given unless consume_in_creative is true.

Cancelled uses

Switching slot, dropping or replacing the held stack, cloning, respawning or logging out cancels the use and any events that haven’t fired yet. Events that already fired stay done.

This matters for when you commit. If an event heals the player at tick 20 but the use commits at the end, a player can switch away at tick 21 and keep the heal for free. Set consume_tick at or before the first event that gives the player something. The default "end" is fine when everything useful happens at the end anyway.

Cooldowns

Field	Type	Default	Meaning
`cooldown`	ticks	`0`	Cooldown started when the use commits.
`cooldown_group`	string	empty	Also blocks every PackEngine item with the same group.
`always_use`	boolean	`false`	Use the item when its block or entity interaction is reached.

The server enforces group cooldowns. Only the item that was used shows the vanilla cooldown overlay; the rest of the group is blocked without it.

always_use is for items meant to be used while looking at a block or entity. Minecraft’s normal interaction order still decides whether the item gets the click at all. It’s also how an item gets an interacted target.

Use requirements

requirements refuses a use before its animation starts:

"requirements": {
  "min_missing_health": 4,
  "min_missing_food": 2,
  "required_effects": ["minecraft:poison"],
  "forbidden_effects": ["minecraft:regeneration"],
  "on_fire": false,
  "failure_translation_key": "message.my_pack.cannot_use_medkit"
}

Field	Type	Default	Meaning
`min_missing_health`	number	`0`	Half-hearts the user must be missing.
`min_missing_food`	integer 0-20	`0`	Food points the user must be missing.
`required_effects`	string or array	empty	Effects the user must have.
`forbidden_effects`	string or array	empty	Effects the user must not have.
`on_fire`	boolean	not checked	`true` needs the user on fire, `false` needs them not on fire.
`failure_message`	string	none	Action-bar message shown when the use is refused.
`failure_translation_key`	string	none	Same, from a lang key. Wins over `failure_message`.