Events

The event timeline

use_events is a list of actions that run during the use animation. The older name use_effects still works, and if an item has both, both run.

"use_events": [
  { "type": "heal", "amount": 4, "tick": 30 },
  {
    "type": "effect",
    "effect": "minecraft:regeneration",
    "duration": 200,
    "amplifier": 1,
    "tick": "end"
  }
]

equip_events and unequip_events take the same event objects with the same timing rules. Their animation filters refer to the equip or unequip clip that was picked. Equip and unequip share one timeline per player, so starting a new equip or unequip replaces the old one. An equip or unequip event with target: "interacted" has nobody to target and is skipped.

Event timing and filters

Field	Type	Default	Meaning
`type`	string	required	One of the action types.
`timing`	enum	`end`	`end` fires once when the clip finishes. `ticks` fires repeatedly in a window.
`from`	ticks or `"end"`	`0`	First tick of the window, included.
`to`	ticks or `"end"`	`"end"`	Last tick of the window, included.
`interval`	ticks, above 0	`1`	Fire every this many ticks in the window.
`tick`	ticks or `"end"`	none	Older shorthand: fire once at this tick.
`animation` / `animations`	string or array	all	Only run when one of these clips was picked.
`target`	enum	`self`	`self`, or `interacted` for the living entity the item was used on.

With timing: "ticks", leaving out from starts at tick 0, leaving out to runs to the last tick, and leaving out interval fires every tick. timing: "tick" means the same as ticks.

Older packs still work:

Leaving out timing but giving from, to or interval picks ticks mode.
tick fires once at that tick.

A tick past the end of the clip is moved back to the clip’s last tick. Animation filters use names from the same family, like use_2, equip_2 or unequip_2.

Heal 0.5 every 10 ticks from tick 20 to 60, only for two of the use clips:

{
  "type": "heal",
  "amount": 0.5,
  "timing": "ticks",
  "from": 20,
  "to": 60,
  "interval": 10,
  "animations": ["use", "use_2"]
}

Using an item on another entity

An interacted target only exists when always_use routes a click on a living entity into the use system. If the item was used on air or a block, events aimed at interacted are skipped.

{ "type": "heal", "amount": 4, "target": "interacted", "tick": "end" }

Action types

Type	Fields	What it does
`heal`	`amount` (above 0)	Restores half-hearts.
`effect`	`effect`, `duration=200`, `amplifier=0`	Applies any registered mob effect, vanilla or modded.
`remove_effect`	`effect`	Removes one mob effect.
`clear_effects`	`category=all`	Clears `all`, `beneficial` or `harmful` effects.
`food`	`nutrition=0`, `saturation=0`	Adds food and saturation to the user.
`damage`	`amount` (above 0), `source=generic`	Deals `generic`, `magic` or `player` damage. `player` is credited to the user.
`extinguish`	none	Puts out fire on the target.
`absorption`	`amount=0`, `mode=add`	`add` to or `set` absorption half-hearts.
`command`	`command`, `permission=2`	Runs a command with the target as `@s`.
`sound`	`sound`, `volume=1`, `pitch=1`	Plays a pack, vanilla or modded sound at the target.
`legendarysurvivaloverhaul:thirst`	`hydration=0`, `saturation=0`	See Legendary Survival Overhaul.
`legendarysurvivaloverhaul:body_heal`	`parts`, `amount`	See Legendary Survival Overhaul.

Mods can add more types. See Custom action types.

effect

Field	Default	Meaning
`ambient`	`false`	Faded, beacon-style display.
`show_particles`	`visible`, else `true`	Show the effect’s particles.
`show_icon`	`visible`, else `true`	Show the HUD icon.
`visible`	`true`	Older field that sets both of the above.
`mode`	`vanilla`	How it combines with an effect the target already has.

Mode	Result
`vanilla`	Minecraft’s normal rules.
`replace`	Removes the old effect first.
`extend`	Adds the old effect’s remaining time to the new duration.
`max`	Keeps the longer duration and the higher amplifier.

Instant effects apply straight away and ignore mode. An effect ID that doesn’t exist is logged once and skipped, so a pack can mention effects from mods that might not be installed.

command

command covers anything Minecraft or another mod can do that PackEngine has no action for. It runs on the server with its output hidden, at the given permission level (0 to 4).

A pack with commands can do anything an operator can. Only install packs you trust, and don’t let people you don’t trust write to the packengine folder.

sound

A bare name resolves in your pack’s namespace, and a namespaced one like minecraft:block.beacon.activate works too. volume can be 0 or more; pitch must be above 0.

food over time

food uses the same timing as every other action. Without a timing field it fires once at the end.

Add 2 food every 5 ticks for the whole animation:

{ "type": "food", "nutrition": 2, "timing": "ticks", "interval": 5 }

Start at tick 15 and keep going every 5 ticks to the end:

{ "type": "food", "nutrition": 2, "timing": "ticks", "from": 15, "interval": 5 }

Only between ticks 15 and 40:

{ "type": "food", "nutrition": 2, "timing": "ticks", "from": 15, "to": 40, "interval": 5 }

The food is real food. It stays until normal hunger uses it up and is capped at the vanilla food limit. It doesn’t raise the maximum.