🔄 Trade Module

The Trade module lets two players open a shared GUI where each places items they want to offer, then both must click Confirm before anything changes hands. Neither player can receive items until both agree — making cheating or scamming impossible.

Quick Start

Installation

Minimum Working Config

enabled: true

Everything else has sensible defaults. Edit only what you need to change.

trade.yml — Full Reference

Located at plugins/OreoEssentials/trades/trade.yml. Every option is explained below.

# ──────────────────────────────────────────────────────────────
#  OreoEssentials — Trade Module Config
#  File: plugins/OreoEssentials/trades/trade.yml
# ──────────────────────────────────────────────────────────────

# Master switch. Set to false to disable the entire trade module.
enabled: true

# Title shown at the top of the trade GUI.
#   <you>  → replaced with the viewer's own name
#   <them> → replaced with the partner's name
# Uses legacy color codes (&8, &7, etc.)
title: "&8Trade — <you> &7⇄ &8<them>"

# Number of rows in the GUI. Keep at 6 — other values are unsupported.
rows: 6

# ── Divider ────────────────────────────────────────────────────
# The vertical bar of blocks that separates your offer area from
# your partner's area (column 4, rows 2–4).
divider:
  material: "PURPLE_STAINED_GLASS_PANE"  # Any Bukkit Material name
  name:     "&5— Trade —"             # Hover name for the divider item

# ── Buttons ────────────────────────────────────────────────────
buttons:
  # The green "Confirm" button before you've clicked it
  confirm:
    material: "EMERALD_BLOCK"
    text:     "&aConfirm"

  # The button AFTER you've clicked Confirm — shown to you while waiting
  # for your partner to also confirm
  confirmed:
    material: "LIME_CONCRETE"
    text:     "&aReady ✔"

  # The red cancel button — closes the trade and returns all items
  cancel:
    material: "BARRIER"
    text:     "&cCancel"

# ── Labels ─────────────────────────────────────────────────────
# Text displayed above each player's offer area (currently used
# in the GUI title substitution).
labels:
  you:  "&fYou"
  them: "&fThem"

# ── Sounds ─────────────────────────────────────────────────────
# All values must be valid Bukkit Sound enum names.
# Find the full list at: https://jd.papermc.io/paper/1.21/org/bukkit/Sound.html
sounds:
  open:    "UI_BUTTON_CLICK"         # Played when GUI opens
  click:   "UI_BUTTON_CLICK"         # Played when toggling confirm off
  confirm: "BLOCK_NOTE_BLOCK_PLING"   # Played when you click Confirm
  cancel:  "ENTITY_VILLAGER_NO"       # Played when trade is cancelled
  complete: "ENTITY_PLAYER_LEVELUP"   # Played when trade completes successfully

# ── Safety ─────────────────────────────────────────────────────

# If true, players must empty their cursor (not be holding an item
# on their mouse) before they can click the Confirm button.
# Prevents accidentally confirming while mid-drag.
require-empty-cursor-on-confirm: true

# Minimum distance in blocks two players must be from each other
# to trade. Set to 0 to allow trading from any distance.
# Works for same-server trades only.
min-distance-blocks: 0

Color Codes

The title, name, and text fields support legacy Minecraft color codes using & as the prefix:

GUI Layout

The trade GUI is a 6-row (54-slot) chest inventory. From Player A's perspective it looks like this (Player B sees an identical layout but their own items are on the left and A's items are on the right):

Slot Details

Important Rules About the Offer Area

How a Trade Works — Step by Step

What Happens to Items During the Trade

While the GUI is open, your offer items remain in the GUI inventory — they are not yet removed from your player inventory. The GUI's offer area is editable, so you can drag items directly out of your hotbar/inventory into the offer slots. When the trade completes, those items swap to the other player. If the trade is cancelled for any reason, the items in the offer slots are returned to your inventory.

Cross-Server Trades

If Player A is on survival-1 and Player B is on survival-2, the trade module handles this automatically using RabbitMQ packets. You do not need to configure anything special — just ensure RabbitMQ is set up in the main config.

How Cross-Server Trades Work

Each trade packet is broadcast over a RabbitMQ exchange. Every server on the network subscribes to these packets. When a packet arrives, a server handles it only if it has the relevant player online. This means the "work" is always done on the server that actually has the player.

Cross-Server GUI Sync

Every time a player changes their offer (adds/removes an item) or clicks Confirm, a TradeStatePacket is sent over RabbitMQ. The remote server receives it and calls applyRemoteState() on the local session mirror, which updates the GUI for the player on the remote server. This keeps both GUIs in sync even across servers.

What If RabbitMQ Is Down?

Cross-server trades will fail to start — the invite will not be delivered to the remote player. Same-server trades are completely unaffected because they never use RabbitMQ.

Invite System

Before a GUI opens, both players must agree to trade via the invite handshake. This prevents GUIs from being forced open on someone who doesn't want to trade.

Invite Flow

Invite Expiry

Already In a Trade

A player who is already in an active trade session cannot accept a new invite. The command will tell them they need to finish or cancel their current trade first.

Confirm & Cancel Flow

Confirming

Click the Confirm button (Emerald Block by default, row 5 col 2). Your button will change to the "Ready ✔" appearance (Lime Concrete by default) and your partner's status indicator will turn green.

Clicking Confirm again un-confirms you (toggles). Your button changes back and your partner's status indicator turns red again. You can change your mind as many times as you like before the trade completes.

What Happens When Both Confirm

The instant the second player clicks Confirm (and both aReady and bReady are simultaneously true):

Cancelling

Either player can click the Cancel button (Barrier by default, row 5 col 4) at any time while the trade is not locked. This:

• Closes both players' GUIs immediately
• Returns all items from both offer areas back to their respective owners
• Sends a cancellation packet to the remote server (if cross-server)
• Removes the session from memory

Disconnecting / Closing the GUI

If a player closes the trade GUI by pressing Escape or using /close, it is treated the same as clicking Cancel — their offer items are returned and the session ends.

Pending Grants

In rare cases, a player might not be online on the correct server at the exact moment a trade finalizes (e.g., they were in the middle of switching servers during a cross-server trade). The pending grants system handles this gracefully.

How It Works

Item Delivery on Join

Delivery happens in TradeService.onJoin(PlayerJoinEvent). Items are added to the player's inventory. If the inventory is full, excess items are dropped at the player's feet (same as normal Minecraft overflow behavior).

RabbitMQ Packets (Cross-Server)

These packets are sent over RabbitMQ between servers. You don't need to configure them — this section is for server administrators who want to understand what's happening on the network.

Trade ID

Each trade has a unique Trade ID (a UUID) computed by TradeIds.computeTradeId(). This ID is deterministic and symmetric — it produces the same UUID regardless of whether you pass (A, B) or (B, A). This means both servers always agree on the trade ID without needing to communicate it first.

// Simplified pseudocode of how the trade ID is computed:
// 1. Sort the two UUIDs alphabetically by their string representations
// 2. Pack the 32 bytes of both UUIDs into a byte array
// 3. Return UUID.nameUUIDFromBytes(thoseBytes)

ItemStack Serialization

Item arrays are serialized using Bukkit's built-in BukkitObjectOutputStream (Java serialization) and then encoded to Base64 for transport over RabbitMQ. This preserves all item data including enchantments, NBT tags, custom model data, and display names exactly as-is.

Commands

Command Behavior Summary

Permissions

LuckPerms Setup Example

# Give all players access to trade
/lp group default permission set oreo.trade true

# Or give everything to a VIP group
/lp group vip permission set oreo.* true

Player Examples

Example 1 — Basic Same-Server Trade

Example 2 — Last-Minute Change of Mind

Example 3 — Cross-Server Trade

Example 4 — Invite Times Out

Example 5 — Partner Disconnects

Example 6 — Inventory Full on Delivery

FAQ