GoodsTrade

Overview

GoodsTrade is a lightweight item trading plugin for Minecraft servers.

It gives both players a shared trade menu with clearly separated offer slots. Players can review, confirm, and cancel before anything changes hands. Offers are locked once confirmed, and a final countdown leaves time to catch a mistake or a last-second item swap.





Features

• Two-player confirmation - The trade only completes after both players approve their offers.
• Final countdown - Either side can still stop the confirmation before the exchange is committed.
• Locked offers - Confirmed players cannot quietly swap items at the last moment.
• Visual GUI - Simple and intuitive GUI trading interface. No complicated commands are required.
• Quick trade request - Players can start a trade with a command, or by sneaking and right-clicking another player if enabled in the configuration.
• Vault money offers - Configurable GUI buttons add or subtract money, validate both balances, and reset stale confirmations after a change.
• Safe returns - Cancelling or closing the menu returns offered items. Overflow is dropped at the player's location instead of disappearing.
• Trade preferences - Each player can disable incoming requests when they want some peace and quiet.
• Item rules - Block items by display name, lore text, an NBT path, or an NBT path/value pair.
• Custom menus - Change button materials, names, lore, and custom model data in View.yml.
• Optional protection - Prevent damage or block movement while a trade is open.
• PlaceholderAPI hook - Read whether a player currently accepts trade requests.
• Chinese and English messages - Switch languages from config.yml and edit either language file freely.

Plugin Information

• Plugin Version:
• Supported Minecraft Versions: 1.12 - 26.1
• Supported Server Software: Bukkit, Spigot, Paper
• Java Requirement: Java 8 or above
• Dependencies: Optional
• Optional Dependency: PlaceholderAPI
• Optional Dependency: Vault plus a Vault-compatible economy plugin, required only for money trading
• Folia: GoodsTrade Lite does not currently claim Folia support.

Installation

1. Download the latest Lite build from GitHub Releases.
2. Place the JAR in your server's plugins directory.
3. Start the server once to generate the configuration files.
4. Edit the files under plugins/GoodsTrade/ and run /gt reload.

Commands

/gt sendtrade [player]
Permission: goodstrade.command.sendtrade
Send a trade request to a specific player.

/gt accept
Permission: goodstrade.command.accept
Accept the only pending trade request.

/gt accept [player]
Permission: goodstrade.command.accept
Accept a trade request from a specific player.

/gt toggle [true/false]
Permission: goodstrade.command.toggle
Enable, disable, or toggle receiving trade requests. Leave out the value to switch the current setting.

/gt trade [sender] [receiver]
Permission: goodstrade.command.trade
Force two specified players to start a trade.

/gt test [virtual-player-name]
Permission: goodstrade.command.test
Open a sandbox trade with a nonexistent virtual player. The administrator controls both sides; no real money or items are exchanged.

/gt reload
Permission: goodstrade.command.reload
Reload configuration, menu items, blacklist rules, and language messages.

/gt
Permission: goodstrade.command
Show command help.


Permissions

goodstrade.command
Default: true
Allows the player to use GoodsTrade commands. Without this permission, no commands can be used.

goodstrade.command.sendtrade
Default: true
Allows the player to send trade requests to other players.

goodstrade.command.accept
Default: true
Allows the player to accept trade requests.

goodstrade.command.toggle
Default: true
Allows the player to enable or disable receiving trade requests.

goodstrade.command.trade
Default: OP
Allows forcing two players to start a trade.

goodstrade.command.test
Default: OP
Allows opening a sandbox trade with a virtual player to test the menu and full confirmation flow.

goodstrade.command.reload
Default: OP
Allows reloading the plugin configuration.


Configuration

The configuration files are located at:

plugins/GoodsTrade/config.yml

plugins/GoodsTrade/View.yml

plugins/GoodsTrade/lang/zh_cn.yml

plugins/GoodsTrade/lang/en_us.yml


Language selection

New installations extract every bundled translation from the JAR. Version 1.1.7 includes zh_cn and en_us.

By default, GoodsTrade follows the server JVM/operating-system locale. Older configs without a Language key behave the same way. If no matching translation is available, the console explains the fallback and GoodsTrade uses Simplified Chinese.

You can also choose a locale explicitly in config.yml:

Run /gt reload after changing the value. Locale names follow the common Minecraft/i18n format, such as zh_cn, en_us, and ja_jp.

GoodsTrade scans the complete lang/ folder inside each new JAR and extracts any translation that is missing on disk. Existing files are never overwritten, so local edits are preserved while newly bundled languages appear automatically.

When upgrading from an older published version, the root-level Lang.yml is migrated to lang/zh_cn.yml when needed. The original file is left untouched.

The command list shown by /gt reads its layout and descriptions from command.help-entry and command.description in the active language file.


Main configuration

• Wait-Time controls the final confirmation countdown in seconds and is capped at 64.
• Economy.Amounts defines one to four button steps. Left click adds the step and right click subtracts it.
• Allow-Negative lets an offer cross below zero; a negative offer means the other player must pay. The divider always shows each player's resulting payment obligation.
• Balance checks run on every amount change, on confirmation, and immediately before settlement. Changing money resets any existing confirmation so both players must review again.
• Shift-Right-Click enables the quick request gesture.
• Safe.Damage cancels damage against players who are currently trading.
• Safe.Move stops block-to-block movement while the trade menu is open.

Item blacklist

The blacklist checks the items a player placed in their offer when they confirm it.

• A Lore or Name rule matches when the configured text appears in the item's lore or display name.
• An NBT path without @ blocks any item containing that tag.
• path@value blocks the item only when the resolved NBT value matches.
• Nested paths use dots. Escape a literal dot in a key with \.

Menu customization

View.yml controls the background, separator, ready buttons, countdown button, cancellation state, and money buttons. Money sets the shared money-button style; Money-1 through Money-4 can override individual steps, and %amount% is replaced at runtime.

Materials are resolved through XMaterial where possible, which keeps names usable across a wide range of Minecraft versions. Unsupported custom model data is skipped on older servers.


Administrator sandbox trade

Players with goodstrade.command.test can run /gt test [virtual-player-name]. The administrator controls both offer areas, both sets of money buttons, and both confirmation buttons, making it possible to verify negative offers, confirmation resets, and the complete countdown without a second online player.

Sandbox trades never call Vault or exchange items. Anything placed on either side is returned to the administrator when the test completes, closes, or is interrupted by a reload. The command cannot be run from the console.


How to Use

Basic Trading Process

1. Start a trade
   
   Use the command:
   
   /gt sendtrade [player]
   
   Or sneak and right-click a player if this feature is enabled in the configuration.
   
2. Accept the trade
   
   Click the [Click to accept] message in chat, or use:
   
   /gt accept
   
3. Place items
   
   Put the items you want to trade into your side of the trade GUI. Money buttons can be used if Vault trading is enabled.
   
4. Confirm the trade
   
   Click the confirmation button. When both players confirm, the countdown starts.
   
5. Complete the trade
   
   After the countdown ends, money is settled if enabled and the items are exchanged automatically.

Trading Notes

• After confirming, trade items are locked and cannot be changed.
• When both players confirm, a 5-second countdown starts by default. This can be changed in the configuration.
• The trade can still be cancelled during the countdown.
• If the trade is cancelled or the GUI is closed, items are automatically returned.
• Changing a money offer resets any existing confirmation. Both players must review and confirm again.

PlaceholderAPI

When PlaceholderAPI is installed, GoodsTrade provides:

%goodstrade_stats%

It returns true when the player accepts trade requests and false when requests are disabled.


Planned Features

• Done: Item blacklist system
• Done: Improved permission module
• Done: Custom GUI materials, lore, and display options
• Done: Vault money trading
• Support for levels and other currencies
• Trade history records
• Custom trade requirements configurable by the server
• Trade cooldown settings
• Suspicious trade warning system
• Cancel trades when players are too far away

Known Issues

• The GUI title may look strange when player names are too long.

Support and Feedback

If you encounter any issues or have feature suggestions, feel free to contact me:

• Email: [email protected]
• QQ Group: 620224543
• Issues: https://github.com/polang233/GoodsTrade/issues

中国用户请加 QQ 群 620224543，反馈最快。其他用户请走 GitHub Issues。

GoodsTrade is released under the GNU General Public License v3.0.