Custom Merchant NPC

CustomMerchant

Turn any NPC into a merchant with a custom shop. No config files, no Asset Editor — just /merchant, link to an existing NPC, and you're set.

I made this because I wanted a simple way to add shops to my server without editing JSON files every time I needed to change a price. Everything happens through a UI: link to any NPC, pick your items, set prices, choose your currency, and configure the animation.

---

How it works

• Spawn an NPC using the Creative Tools
• Freeze it with the Entity Tool (recommended)
• Look at the NPC and run /merchant
• Click "Link to NPC" to connect the merchant data to that NPC
• Configure the shop content and animation

You can edit already existed merchant in creative just by looking them and pressing F

Players walk up to the linked NPC, press F, and the shop opens.

The currency system uses actual items from your inventory (not hotbar). If you set Fire Essence as currency and an item costs 50, players need 50 Fire Essences in their inventory to buy it.

---

NPC animations

Once linked, you can choose an animation for your merchant NPC. The animation list is automatically detected from the NPC's model. Select "Sleep", "Idle", "Sit", or any available animation — it persists through server restarts.

<!> Update from 1.2.3 to 1.2.4 warning ! <!>

• Npc will spawn 2 time if you unload and load the chunk, delete both, this should happen only the first time it's done, then the data should be update to 1.2.4 and not happen again

---

Auto-restock

You can set a restock timer (in minutes) when configuring a merchant. Stock refills automatically based on real time, so if you set 60 minutes the shop restocks every hour even if nobody's online. When items are out of stock, players see "Restocks in: Xh Xm" instead of the buy button.

If you need to restock everything immediately: /restockmerchant

---

Editing merchants

Switch to Creative mode and press F on any merchant to open the edit screen. From there you can:

• Add, edit, or remove items
• Change the restock interval or force a restock
• Change the NPC animation
• Delete the merchant entirely

---

Commands

/merchant — Opens the merchant builder (OP only)

/restockmerchant — Force restock all merchants (OP only)

---

Available currencies

Any item can be used as currency — just drag it to the currency slot when configuring an item.

Default is Fire Essence

---

Good to know

• Data saves to JSON and persists through restarts
• Shop UI shows green prices when you can afford something, red when you can't
• NPCs are identified by UUID, so they persist even after world reload
• Linked NPCs keep their original model and appearance — only the interaction changes

---

What's next

• Translation ?
• "Ecotale" compatibility

---

Know issue

• You can't put NPC Dialog & NPC Quests on a Custom Merchant NPC
• "Crash - CustomUI Set command couldn't set value. Selector: #InventoryGrid.Slots" after update : move/delete item from your inventory to "refresh" it, do it a couple time and it should work again

---

Changelog:

v1.2.4 — New Link System

• Complete rework: link merchants to existing NPCs instead of spawning new ones
• Animation selection with persistence
• Improved UI
• <!>Can Wipe your merchant<!>

v1.2.3 — Complete UI overhaul

v1.2.2 — Scheduler checks every 30 seconds and respawns NPCs if necessary

v1.2.1 — Fix NPC despawn issue

---

v1.2.4 — Dr1mS