trade/README.md

Trade

Trade is a NeoForge mod for Minecraft 1.21.1 that adds a secure player-to-player trading interface inspired by Runescape.

Players can request a trade, review both offers in a shared GUI, accept once to lock the offer, and confirm a second time to complete the exchange.

Features

• Player-to-player trade requests with an accept / decline handshake
• Shared trade screen with separate offer areas for both players
• Two-step confirmation flow
• Quantity-based item selection with quick amounts and Trade X
• Warning if items are removed/modified
• Inventory-safe finalization: nothing changes until safety and security checks pass and the trade succeeds
• Configurable trade safety checks to prevent dangerous mid-combat or mid-movement trading
• Configurable per-player request cooldowns
• Per-player trade toggles and ignore list support
• Admin-controlled player and item trade blacklists, with config defaults and live commands
• File-based trade audit log for server operators

Player Usage

Starting a trade

Primary flow:

• Use the trade keybind (default: G) while looking at another player

Command option:

/trade <player>

When a request is sent, the target player receives chat text with a clickable accept link.

They can also respond manually:

/trade yes
/trade no

In the trade screen

• Click an item in your inventory to trade 1
• Right-click an item to open the quantity menu
• Use Trade X to enter a custom amount
• Click Accept when your offer is ready
• Once both players accept, the screen enters the confirmation stage
• Click Confirm to finalize

If a player reduces or removes items from an offer:

• any pending accepts / confirms are invalidated
• the changed offer slot gets a blinking red border and !
• the trade window shows a red Trade Modified warning

Commands

Player commands

/trade <player>
/trade yes
/trade no
/trade toggle
/trade on
/trade off
/trade ignore <player>
/trade unignore <player>
/trade ignorelist

Admin commands

Server operators can manage persistent live blacklists with:

/trade admin playerblock add <player|uuid>
/trade admin playerblock remove <player|uuid>
/trade admin playerblock list
/trade admin itemblock add item <namespace:item>
/trade admin itemblock remove item <namespace:item>
/trade admin itemblock add tag <namespace:tag>
/trade admin itemblock remove tag <namespace:tag>
/trade admin itemblock add mod <modid>
/trade admin itemblock remove mod <modid>
/trade admin itemblock list

Command behavior

• /trade <player> sends a trade request
• /trade yes accepts the current pending trade request
• /trade no declines the current pending trade request
• /trade toggle flips whether you accept incoming trade requests
• /trade on enables incoming trade requests
• /trade off disables incoming trade requests
• /trade ignore <player> blocks trade requests from that online player
• /trade unignore <player> removes that online player from your ignore list
• /trade ignorelist shows your ignored players

Trade Safety

By default, the mod blocks trade requests or acceptance unless both players are in a safe state.

Default safeguards:

• on solid ground
• standing still
• not recently damaged
• not on fire
• not in liquid
• not sleeping
• not gliding
• not mounted
• in the same dimension

There is also a special delayed-accept flow for the most common transient failure:

• if the other player accepts while you are only moving or in the air, the request does not fail immediately
• instead, you get an on-screen countdown
• if you get safe in time and remain still long enough, the trade opens automatically

Final Validation

When both players confirm, the trade is checked one last time before any real inventory is changed.

The trade verifies:

• both players are still in the same dimension, if that config is enabled
• both players are still within configured trade distance, if enabled
• both live inventories still match the snapshots taken when the trade started
• both players can receive the incoming items
• both players have re-accepted after any offer changes

If any check fails, the trade is cancelled and both players receive an explicit chat message explaining why.

Configuration

Server config values live under the trade section.

Request / range

• tradeCommandProximity

  • default: 0
  • 0 disables range checks
  • 1+ requires players to be within that many blocks to request, accept, and finalize a trade

• requestTimeoutSeconds

  • default: 30
  • number of seconds before a pending trade request expires

• requestCooldownSeconds

  • default: 5
  • number of seconds a player must wait before sending another trade request

Debug

• enableDebugFeatures
  • default: false
  • enables debug commands and debug UI/testing tools

Trade flow

• requireSecondConfirmation

  • default: true
  • requires the second confirm step after both players accept the offer

• showTradeModifiedWarnings

  • default: true
  • shows the Trade Modified warning and changed-slot highlights when offers are reduced or removed

Safety

• requireOnGround

  • default: true

• requireStationary

  • default: true

• stationarySpeedThreshold

  • default: 0.03

• requireNoRecentDamage

  • default: true

• noDamageSeconds

  • default: 10

• requireNotOnFire

  • default: true

• requireNotInLiquid

  • default: true

• requireNotSleeping

  • default: true

• requireNotFallFlying

  • default: true

• requireNotRiding

  • default: true

• requireSameDimension

  • default: true

Admin blacklists

• adminDisabledPlayerUuids

  • default: []
  • UUIDs of players who cannot use the trade system at all

• adminBlacklistedItemIds

  • default: command blocks, command block minecarts, barriers, bedrock, end portal blocks/frames, structure blocks, jigsaws, lights, and spawners
  • exact item ids that cannot be traded, like minecraft:diamond

• adminBlacklistedItemTags

  • default: []
  • item tags that cannot be traded, like minecraft:logs

• adminBlacklistedMods

  • default: []
  • mod namespaces that cannot be traded, like minecraft

Config blacklist entries are treated as defaults. Live admin commands add and remove separate saved entries that persist across restarts.

Audit Log

The mod writes a trade audit log to:

logs/trade.log

Entries include:

• trade requests
• request accepts / declines / expirations
• trade opens
• trade cancels
• trade completions
• player names
• UUIDs
• dimensions
• block coordinates
• items offered by each side
• final result text

Debug Mode

Debug tools are disabled by default and only available when:

• enableDebugFeatures = true

When enabled, the mod exposes /trade debug ... commands and on-screen debug controls for single-client testing.