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:
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.