How to create NPCs that sell items to the players and buy their items, configured in the admin panel.

How it works in the game

The player clicks the trader when it is in range and the dialog shows its text with the Buy and Sell buttons:

• Buy lists the items of the trader with their price. The player sets the quantity, clicks the cart button to add the item to the exchange column (the x removes it) and clicks confirm: the price is taken from the player inventory and the items are added to it.
• Sell lists the player items that the trader buys (only the items that are not equipped and have a sell value). The player adds them to the exchange column in the same way and on confirm they are removed from the inventory and the payment is added.
• The trader stock never changes: buying does not decrease it and the sold items are not added to it.

The sample merchant Gimly (npc_3) in the town sells an axe for 5 coins, a spear and the heal and magic potions for 2 coins each, and buys them back (and the ore from the mining rocks) for 1 or 2 coins.

Setting up a trader in the admin panel

1. Open Game Objects > Objects and create the NPC (or duplicate the sample merchant) with the Class Type trader, placed like any other object (see Objects Entity).
2. Set the dialog text in the Client Params content. The options must use the buy and sell values (they are the default when options is missing), keep only one of them for a trader that only sells or only buys.
3. Open Game Objects > Objects Items Inventory and add one row per item the trader sells: the trader in Owner ID, the Item ID and -1 in Qty (no quantity limit per purchase).
4. Open Game Objects > Trade - Items Requirements and add the price of each item: the trader in Object ID, the sold item in Item Key, the payment item (for example coins) in Required Item Key and the Required Quantity for one unit. Check Auto Remove Requirement so the payment is taken automatically from the player inventory.
5. Open Game Objects > Trade - Items Rewards and add what the trader pays for each item it buys: the trader in Object ID, the bought item in Item Key, the payment in Reward Item Key and the Reward Quantity for one unit. Leave Reward Item Is Required unchecked so the trader always has the payment.
6. Restart the server to load the trader.

The sample merchant uses:

// Private Params
{"runOnAction":true,"playerVisible":true,"sendInvalidOptionMessage":true,"collisionType":4,"hasState":true,"randomMovement":{"maxTiles":5}}

// Client Params (without the animations)
{"content":"Hi there! What would you like to do?","options":{"buy":{"label":"Buy","value":"buy"},"sell":{"label":"Sell","value":"sell"}},"autoStart":true}

Configuration reference

• The quantity a player buys or sells multiplies the required and the reward quantities: 3 spears cost 6 coins.
• Without Auto Remove Requirement the player has to add the payment items to the exchange, and the buy fails when they are missing.
• With Reward Item Is Required the trader must own the reward item in its inventory with enough quantity, otherwise the sell fails.
• The equipped items are never offered for sale, and an item without a Trade - Items Rewards row is not listed in Sell.
• The default dialog text, the button labels and the confirmation texts ("Thanks for buying!" and "Thanks for your products!") are the objects.trader client translations (lib/objects/client/snippets/en_US.js).

Code integration (advanced)

• Server class: TraderObject (lib/objects/server/object/type/trader-object.js), an NPC that loads its Objects Items Inventory, requirements and rewards on start and runs each trade through the @reldens/items-system exchange Processor (init, add, remove and confirm).
• The trader inventory is the exchange side A, created with dropExchangeA (the items the player sells are not added to it) and, on buy, avoidExchangeDecreaseA (the sold items are not removed from it).
• Client: TraderObjectUi (lib/objects/client/trader-object-ui.js) renders the items, the exchange column and the buttons from the traderObject messages.
• The exchange options are explained in Items System Architecture.

For trading between players see Trade System.