Dispenser Vilager Trading

Dispenser Villager Trading

Dispenser Villager Trading is a Paper plugin that allows dispensers to perform villager trades automatically.
When a dispenser faces a villager and contains the required ingredients for one of the villager's trades, it will automatically:

• Select a valid trade (at random, preserving vanilla dispenser behavior),
• Pay the cost using items from its inventory,
• Drop the result behind the dispenser (or insert it into a chest located directly behind it),
• Update villager experience and trade usage as if a player traded manually.

This plugin also adds a villager-only pressure plate that only villagers can activate.

Features

• Dispenser trading: Dispensers can fulfill any available villager trade — including two-ingredient trades — using their own inventory. Villagers gain experience and trades lock/unlock as normal.
• Player Experience: Players gain experience as if they traded manually when dispensers perform trades. Same as Furnace Experience.
• Villager-only pressure plate: A custom craftable pressure plate (stone pressure plate + emerald) that only villagers can activate.

Public API (Event System)

A dedicated API module exposes events for other plugins.

The first event is:

DispenserVillagerTradeDepositEvent

This event fires whenever the plugin attempts to deposit a villager trade result into a chest.

Available methods:

public Inventory getSource();
public Inventory getDestination();

public ItemStack getItem();
public void setItem(ItemStack item);

public boolean isCancelled();
public void setCancelled(boolean cancel);

public HandlerList getHandlers();
public static HandlerList getHandlerList();

Requirements

• Paper 1.21.10 (or any Paper build targeting the 1.21.10 API)
• Java 21 runtime on the server

Installation

1. Build the plugin JAR (see below) or download one from the releases page.
2. Place the JAR into your server's plugins/ directory.
3. Start or reload your Paper server.

Building

This project uses Gradle. Common tasks: You can build only the plugin JAR, copy it to a server, or run a local test server.

• ./gradlew build — Builds the plugin JAR under plugin/build/libs/.
• ./gradlew copyToServer — Builds the JAR and copies it to the server directory specified by SERVER_LOCATION in secrets.properties.

Configuration

The generated config.yml provides the following option:

• allowVillagerDispenserInteractions (boolean):
  If false, dispensers will not fire when a villager stands in front of them unless a matching trade exists.
  Defaults to false.

Usage Tips

• Place a dispenser facing a villager, load it with the required trade ingredients, and power it. The plugin selects a valid trade, consumes the payment, and outputs the result behind the dispenser.
• Craft the villager-only pressure plate (stone pressure plate + emerald) to allow villagers — and optionally players — to activate contraptions while preventing other mobs from triggering them.
• Place a chest directly behind the dispenser to automatically collect traded items.

Notes

The plugin is designed specifically for Paper and may not function correctly on other server types.

It aims to preserve core vanilla behavior while adding helpful mechanics:

• Trades are selected randomly, matching vanilla dispenser behavior.
• Villager experience and trade usage update normally.
• Result items are dispensed naturally, as if fired by a dispenser.
• Additional quality-of-life features:
  • Traded items are dispensed behind the dispenser so villagers don't pick them up.
  • Chests placed behind the dispenser collect trade outputs automatically.
  • A villager-only pressure plate allows villager-driven redstone without mob interference.

Future Plans

• Selecting a specific trade via redstone signal strength.
• Moving the villager-only pressure plate to a dedicated plugin. Or adding more pressure plate types.
• Add more events to the public API for deeper integration.
• Add barrels support for trade result collection.
• Add more configuration options to better mimic vanilla behavior.

Feedback and Contributions

Feedback, issues, and pull requests are welcome!
Visit the GitHub repository: DispenserVillagerTrading