Pipelines

How a pipeline gets wired up

1. The blueprint is deserialised. The pipeline type strings are looked up in PipelineService's registry, which maps block-break → BlockBreakPipelineHead.class, hammer → HammerPipelineLink.class, and so on. Each component's fields are deserialised as a @ConfigSerializable record / bean.

2. PipelineService.initialize() walks every loaded blueprint and reads the @PipelineHeadMeta annotation off the head class. The annotation says which Bukkit event and at what priority the head wants to run.

3. EventService registers one dummy listener per (EventPriority, Event) pair. The dummy listener routes incoming events into an EventNode and from there into matching EventEntry instances:

   • preChecks — heads whose @PipelineHeadMeta(checkItem = false) runs item-agnostically (currently none registered; reserved for global hooks).

   • postChecks — heads keyed by the blueprint Key they belong to.

4. At runtime, when Bukkit fires the event, EventProcessor.process(event, node) runs:

   • Resolve every ItemStack the event carries via the registered EventContextAdapter for that event type.

   • Pull each ItemInstance out of the PDC and look up matching postChecks entries by blueprint key.

   • The adapter builds a PipelineContext — including any extra context the event needs (for example DragAndDropContext for InventoryClickEvent).

   • Check requirements; on failure cancel the event and skip the pipeline.

   • Invoke head.handle(event, context) — if it returns false, skip the pipeline.

   • Run every chain link in order, then every tail in order.

   • If context.dirty() was set by a link, persist the updated ItemInstance back to the stack at the end of the run. If context.replaceItemStack() is also set, swap the live ItemStack for the one in context.itemStack() (used by scalable item evolution).

PipelineContext

PipelineContext is the data bus that flows through a pipeline run. Heads populate it from the event, links transform it, tails consume it.

Immutable inputs (set when the context is built):

Mutable state (populated by the head, mutated by links, consumed by tails):

PipelineContext doubles as a placeholder source: it implements Function<String, Object> and exposes a PlaceholderContainer pre-populated with player_*, item_* (via ItemStackPlaceholder), the instance_* placeholder, location_* if a location was captured, and an extra-context_* namespace for every adapter-supplied extra (e.g. extra-context_drag-and-drop_cursor_material). See Placeholders for the full list.

Any PlaceholderWrapper<T> in a component config — amount, multiplier, chance — resolves through this container, so you can write:

Authoring a pipeline

A pipeline is declared inside a blueprint's pipelines block. The map key is the pipeline's id (unique per blueprint), the value is the pipeline definition:

The pipeline above:

1. Captures BlockBreakEvent only for stone-family blocks (head whitelist).

2. Adds neighbouring blocks' drops to the context via hammer.

3. Takes 1 durability from the item via take-durability.

4. Sends everything in drops straight to the player's inventory via magnet.

For the full catalogue of components see:

• Pipeline Heads

• Pipeline Links

• Pipeline Tails

Type registry

PipelineService registers components under short string IDs. These are the strings you put in type:.

The registry is populated in PipelineService's constructor. Custom components are not yet pluggable from outside the plugin.