Pipeline Heads

block-break

Event: BlockBreakEvent — priority: HIGH

Captures broken blocks: it replaces their natural drops with an empty drop list (drops are accumulated in the context instead, then handed off to tails) and stores the block, its location, and the natural XP. On top of the single broken block it also, by default:

• empties the contents of a broken container (chest, barrel, …) into the drop list — the correct half of a double chest is handled; shulker boxes are left intact so they keep their contents;

• adds a broken bed's placement item to the drops;

• breaks the whole vertical column of a broken stackable plant (SUGAR_CANE, BAMBOO, KELP, CACTUS) and captures its drops + XP;

• breaks any attached / physics-dependent blocks that would pop off (torches, rails, …) and captures their drops + XP.

Each of those extra breaks fires a virtual BlockBreakEvent so protection plugins can veto them.

The head sets event.setDropItems(false) and event.setExpToDrop(0) — tails are then responsible for dropping the items back on the ground (drop), giving them to the player (magnet), or mailing them (mailbox). Without a tail the broken block silently disappears.

entity-damage

Event: EntityDamageByEntityEvent — priority: HIGH

Captures entity damage and optionally rescales it. Stores the damaged entity in context.

entity-kill

Event: EntityDeathEvent — priority: HIGH

Captures the killed entity's natural drops and XP into the context, clearing them on the event. Records entity, location, and vanillaExperience.

Skips the pipeline if the kill has no killer (the entity died without a player credited).

bucket-entity

Event: PlayerBucketEntityEvent — priority: HIGH

Fires when the item is used to bucket an entity (axolotl, fish, …). Stores the entity and its location.

fish

Event: PlayerFishEvent — priority: HIGH

Fires only when the fishing state is CAUGHT_FISH and the caught entity is an Item. Adds the caught ItemStack to drops and sets location to the hook position.

No configurable fields.

interact

Event: PlayerInteractEvent — priority: HIGH

Fires on left- or right-click of a block or air. Filters by action and target block material.

interact-entity

Event: PlayerInteractAtEntityEvent — priority: HIGH

Fires on right-clicking an entity. Stores the entity in context.

equip-hand

Event: HandEquipEvent — priority: HIGH

Fires when the custom item enters the player's main hand (also fires on interaction with item frames / armour stands and on quit; see the event docs).

No configurable fields — the head simply opens the pipeline so chain links can run on equip.

drag-and-drop

Event: InventoryClickEvent — priority: HIGH

Fires when the player drags one item onto another in any inventory. The pipeline runs on the slot item (the item in the clicked slot, which is context.itemStack()) and exposes the cursor item through a DragAndDropContext extra context.

Common use cases:

• Consumable upgrade orbs that mutate the slot item (e.g. a repair orb dropped onto a damaged tool).

• Tools that "store" a material picked up from the cursor (e.g. a build wand that remembers which block to place).

The head is skipped if the cursor is empty or — when tags is set — the cursor is not a custom item or none of its blueprint tags match.

harvest-block

Event: PlayerHarvestBlockEvent — priority: HIGH

Fires when a player harvests a block that drops items without breaking (sweet-berry bushes, cave vines, …). Captures the harvested block, its drops, and the hand slot, then clears the event's harvested items so the drops flow to tails instead.

shear-block

Event: PlayerShearBlockEvent — priority: HIGH

Fires when the item is used to shear a block (pumpkin, beehive, …). Captures the block, its drops, and the hand slot; the natural drops are cleared so they flow through the pipeline to tails.

No configurable fields.

shear-entity

Event: PlayerShearEntityEvent — priority: HIGH

Fires when the item is used to shear an entity (sheep, mooshroom, …). Captures the entity, its drops, and the hand slot; the natural drops are replaced with an empty list so they flow to tails.

No configurable fields.

equip-armor

Event: ArmorEquipEvent — priority: HIGH

Fires when the custom item is equipped into an armour slot. Stores the item and its EquipmentSlot — no drops, block, or entity are captured, so this head is meant for running links on equip (e.g. execute-actions, attribute buffs).

No configurable fields.

unequip-armor

Event: ArmorUnEquipEvent — priority: HIGH

The counterpart to equip-armor: fires when the custom item leaves an armour slot. Stores the item and its EquipmentSlot.

No configurable fields.

Material tags

Fields typed List<Tag<Material>> (such as allowed-tags) accept Bukkit material tags in two forms. The registry defaults to blocks, and an unresolvable tag key fails to load:

Shared base fields

Every head inherits two base fields from PipelineHead:

The @PipelineHeadMeta(checkItem = false) annotation also exists for declaring item-agnostic global hooks (the head fires for every event of its type, not just events carrying a matching custom item). No built-in head uses it today — see PipelineContext › How a pipeline gets wired up.