Skip to content

Trading and restocking

Set interaction_mode to trade to open the shop on right-click. The GreatNPC client mod is required for the custom trading screen.

Item trade

This partial trainer preset sells three Poké Balls for two gold coins.

{
  "interaction_mode": "trade",
  "trades": [
    {
      "id": "poke-balls",
      "cost_a": "greatnpc:coin_gold",
      "cost_a_amount": 2,
      "result_type": "item",
      "result": "cobblemon:poke_ball",
      "result_amount": 3,
      "max_uses": 5,
      "reset_minutes": 60,
      "xp": 0,
      "conditions": []
    }
  ]
}
Field Meaning
cost_a, cost_a_amount First payment item and quantity. Blank item ID makes this cost free.
cost_b, cost_b_amount Optional second payment item and quantity.
result_type item or command.
result, result_amount Reward item and quantity; for commands, result supplies the display icon.
result_label Custom display text for a command reward.
result_commands Commands run for a command reward.
max_uses Per-player use limit; 0 means unlimited.
reset_minutes Reset period for the use limit when rotating stock is disabled; 0 never resets.
xp Minecraft experience points granted after a successful trade.
conditions Requirements for availability.
weight Relative selection weight when rotating stock is enabled.

Both costs are planned together. If they accept the same inventory stacks, a stack cannot pay both costs without enough total items. The server validates the transaction; the affordability filter in the GUI is only a preview.

Exact items and components

Use Choose from inventory in the editor to copy a cost, reward or icon. The picker includes hotbar, normal inventory, armor and offhand. It copies the item definition without consuming it; quantity is configured separately.

The fields cost_a_nbt, cost_b_nbt and result_nbt store serialized component changes, not a whole legacy item-stack NBT compound. Prefer the picker to hand-writing these values. Cost matching checks the specified component requirements; unrelated additional components on the player's item are not automatically rejected.

Malformed component requirements or item rewards are rejected before payment. Invalid item IDs also prevent an item trade. Custom command rewards are different: a command failure cannot atomically undo an already charged trade. Test reward commands before selling them.

Command reward

The following is an offer object for the trades array:

{
  "id": "rare-candy-command",
  "cost_a": "greatnpc:coin_gold",
  "cost_a_amount": 3,
  "result_type": "command",
  "result": "cobblemon:rare_candy",
  "result_label": "<gold>Three Rare Candies</gold>",
  "result_commands": [
    "give %player% cobblemon:rare_candy 3"
  ],
  "max_uses": 1
}

Trade reward commands run on the server, with the interaction placeholders substituted. A blank result_commands list produces no command reward even if the offer has a display label.

Rotating stock

Add these properties to the trainer preset:

{
  "trade_restock": true,
  "trade_restock_minutes": 30,
  "trade_restock_count": 3
}

The shop chooses up to the configured number of offers from the full list. Selection is weighted and without replacement: weight: 4 has four times the selection weight of weight: 1; weight: 0 excludes an offer from selection.

Restock duration is clamped to 1–10080 minutes, and offer count to 1–100. The actual selected count can be smaller if fewer offers have positive weights. The timer and selected offers are shared by players viewing that NPC; usage limits remain per player. Each stock cycle gives those limits a new counter. reset_minutes is not used while rotating stock is active.

Rotating stock is persisted in the world's greatnpc/trade_restock.json. The next rotation is evaluated when the shop is accessed after its timer expires. A server restart does not itself mean a new cycle. Stable, unique offer IDs are essential because stock membership and per-player usage refer to them.