PiglinTrades

A lightweight Spigot/Paper 1.21+ plugin that lets both special Piglins and (optionally) regular Piglins trade via fully configurable, weighted reward pools. Players “offer” an item, the Piglin admires it for a short cooldown (shows it in off-hand so weapons aren’t lost), then drops a reward based on your config. Supports item rewards (incl. potions & enchanted books) and console command rewards — with optional PlaceholderAPI placeholders.

---

Highlights

• Special Piglins: Invulnerable, don’t despawn, show the offered item while “thinking,” then pay out.
• Regular Piglins (toggle): Keep vanilla bartering or switch them to PiglinTrades via config.
• Off-hand admire: Offered item appears in off-hand so Piglins keep their main-hand weapon.
• Item-keyed pools: Each pool is keyed by the MATERIAL the player offers (e.g., GOLD_INGOT).
• Weighted rewards: Per-entry weight controls odds; amounts can be fixed or ranges.
• Reward types:
  • Item (supports enchants; potions via base PotionType; tipped arrows)
  • Enchanted books (stored enchants)
  • Command (runs from console; supports {player} and PlaceholderAPI)
• Admin GUI & tools: Add/edit pools and rewards in-game; simulator to test odds.

---

Requirements

• Server: Spigot/Paper 1.21+
• Java: 21+
• Optional: PlaceholderAPI (for placeholders in command rewards)

---

Installation

1. Drop PiglinTrades.jar into /plugins.
2. (Optional) Install PlaceholderAPI if you want placeholders in command rewards.
3. Restart to generate config.yml and rewards.yml.
4. Customize settings, then run /pt reload.

---

Quick Start

1. /pt spawn to place a Special Piglin.
2. In rewards.yml, create a pool keyed by the item players will offer (e.g., GOLD_INGOT).
3. Offer the item by right-clicking the Piglin or dropping it near them (consumes 1).
4. After the cooldown, a reward from the matching pool appears.

Want regular Piglins to use the plugin too? See the config toggle below.

---

Configuration

config.yml

• cooldown-seconds — Seconds a Piglin “admires” the item before payout (default: 3).
• allow-vanilla-piglin-barter — If true, regular Piglins keep vanilla bartering. Special Piglins always use PiglinTrades.
• regular-piglins-use-plugin-trades — If true, regular Piglins also trade via PiglinTrades.

These two booleans are mutually exclusive. If both are true, the plugin logs a warning and disables vanilla bartering, making regular Piglins use PiglinTrades.

Example:

cooldown-seconds: 3
allow-vanilla-piglin-barter: false
regular-piglins-use-plugin-trades: false

rewards.yml (concept)

• Pools are keyed by MATERIAL names (e.g., GOLD_INGOT).
• Each pool has entries with:
  • type: item | enchanted_book | command
  • weight: higher = more likely
  • For items: material, amount (number or min-max), optional enchants, optional potion
  • For enchanted books: stored_enchants, amount
  • For commands: command (console), supports {player} and PlaceholderAPI

Tip: /pt simulate <POOL_KEY> <COUNT> to preview outcome distribution.

---

Commands & Permissions

• Base: /piglintrades (alias /pt)
• Perm: piglintrades.admin (default: OP)

Subcommands:

• /pt spawn — Spawn a Special Piglin.
• /pt reload — Reload configs.
• /pt simulate <POOL_KEY> <COUNT> — Test weighted outcomes.
• /pt kill <all|nearest> — Remove Special Piglins.
• /pt gui — Open the admin GUI.

---

How players use it

• Special Piglins: Right-click or drop a configured item; wait the cooldown; collect reward.
• Regular Piglins:
  • If allow-vanilla-piglin-barter: true → they behave vanilla.
  • If regular-piglins-use-plugin-trades: true → they use the same PiglinTrades flow as specials.

---

Notes

• Offered items show in the Piglin’s off-hand while admiring (main-hand gear stays intact).
• If a pool has no valid entries or only non-positive weights, it won’t select a reward.
• Validate MATERIAL names and enchant keys against Spigot enums.

---

Troubleshooting

• Regular Piglin still barters vanilla → Set allow-vanilla-piglin-barter: false and regular-piglins-use-plugin-trades: true, then /pt reload. Check console for the mutual-exclusivity warning if both were true.
• “Unknown pool” in /pt simulate → Verify the exact MATERIAL key.
• No rewards dropping → Check entry type, weights, and fields.
• Placeholders not applied → Install PlaceholderAPI and required expansions.