Shopkeepers

Table of Contents

logo

Set up custom villager shopkeepers that sell exactly what you want them to sell and for what price. You can set up admin shops, which have infinite supply, and you can also set up player shops, which pull supply from a chest.

It will also prevent any other trades with non-shopkeeper villagers, if you want it to.

For those who are simply looking for a convenient way to modify the trades of vanilla villagers (as an alternative to using complex Minecraft commands), the plugin also includes a graphical editor for regular villagers and wandering traders.

Basic Features

Easily create villager shopkeepers that trade the items you want them to trade.
Admins shops with infinite supplies.
Player shops which pull supplies from a chest.
Different types of player shops: selling, buying, trading, and selling books.
Various supported mob types to represent your shopkeeper, sign shops, and Citizens (NPC) shops.
Editor for regular villagers and wandering traders.
Many configuration options.
Translatable messages.
Open source (Source code on GitHub)

Supported server versions

Shopkeepers supports the latest versions of Bukkit / Spigot.
Note that this plugin is created to work with CraftBukkit (or alternatively Spigot). Bukkit does not have an API for some of the things necessary to make this plugin work. This means that other server software (Tekkit, Forge, Cauldron, etc.) will not work with this plugin.
Other CraftBukkit or Spigot derivatives/forks might work, but are not officially supported. So if you run into issues while using those, try to reproduce your issue on a fresh and up-to-date Spigot server first.

Getting started

All documentation can be found in the wiki:

Showcase

Admin shops:

Configure the trades via the in-game inventory menu:

setup-admin-shop-text

Resulting trading menu:

setup-admin-shop-result

Player shops (ex. selling items):

Fill the shop chest with supplies:

Configure the trades via the in-game inventory menu:

Resulting trading menu:

Video Tutorials

More video tutorials can be found in the wiki: https://github.com/Shopkeepers/Shopkeepers-Wiki/wiki/Video-Tutorials

Tutorial by Donnie, explaining the setup of the different shop types:

Tutorial by Fan Staaff showing the setup of the different shop types in detail:

Tutorial by LastKing2X,showing the setup of the different shop types:

Spanish tutorial by Ajneb97, also mentioning placeholder items and various config options:

Statistics

This plugin uses bStats to collect anonymous plugin usage statistics. This helps me to determine how many servers are using the plugin, which Minecraft versions it is used with the most, and to which degree the different features are used.

Here is a list of all currently tracked information:

Common information: The number of servers using the plugin, the number of players on these servers, online mode, Minecraft version, plugin version, core count, system arch, operating system, server country, Java version.
Shopkeepers specific information: Whether specific related plugins are used (Citizens, Towny, WorldGuard, Gringotts, other Vault economy plugins), number of shops, whether player shops are used, whether certain features are enabled in the config (ex. WorldGuard/Towny compatibility, Citizens shops, delayed saves, colored names, chest protection, removal of inactive shops, tax rate, strict item comparison, purchase logging, disabling of other villagers, ..), the number of worlds containing shops.
All information can be publicly viewed here: https://bstats.org/plugin/bukkit/Shopkeepers/

If you want to disable bStats for all plugins on your server, edit the file plugins/bStats/config.yml, or alternatively disable it only for Shopkeepers by setting 'enable-metrics' to 'false' inside the Shopkeepers config.

Known potential issues

A list of known potential issues of the latest version of Shopkeepers can be found in the wiki: This documents differences between Minecraft/Spigot versions, and existing Minecraft/Spigot issues related to Shopkeepers.

If you run into an issue, check if this list already contains and maybe offers information on how to handle it.

Have issues or further questions?

If you have a pressing issue or simple question, you can join the discord server and ask other plugin users for help:

But submitting a ticket is the best way to get help or report a problem with the plugin.

Before submitting a ticket:

Check if your question is already answered in:
- The documentation (wiki).
- The FAQ.
- The Known Issues.
Check if there is already another ticket for your issue.

Before reporting an issue:

Try to reproduce your issue when using:
- The latest versions of Spigot and Shopkeepers.
- No other plugins.
- No kinds of other server or client mods.

When reporting an issue:

Provide the versions you are using of Minecraft, Spigot and Shopkeepers.
Provide a detailed description of your problem and add as much information as possible which could help reproducing the issue.
If possible, include step-by-step instructions on how to reproduce the issue on a fresh Spigot server.

Donations

If you like this plugin, consider supporting its developers by making a donation:

To blablubbabc (current maintainer: Dec 2013 - today)
To nisovin (former author: Aug 2012 - Dec 2013)

A big "thank you" to everybody who is keeping the motivation up through donations!

Minecraft-Servers-Listing.com	TRS Game Servers	terminalserver.us
Minewind	mercurialmusic	timitimitimi
FatherWh0 (merchantvillages.com)	lukeeexd (tws-mc.com)	PapaJuan
EmeraldHaze (Ninjalette)	Espen	kbtalkin
Dimo (Beyond Vanilla)	RefugiaCraft	Frilioth
Tabletopcheese	Observant Minecraft Server	Ren B.
BadWolfMC	Michael M.	Alejandro A.
Michael B.

Want to help?

Whether you are a programmer or not, there are many ways in which you can contribute! For example:

Help users with issues and questions on Github, Discord, or the comment section.
Create and update translations.
Keep the documentation (the wiki) up-to-date with plugin updates.
Write or maintain add-on plugins (see the open Github issues).

If you are interested or have other ideas on how you can contribute, feel free to contact me via PM.

Add-On Plugins

Sometimes, a feature is either to specific to include directly into the Shopkeepers plugin, or I did not yet have the time to add something similar myself. You can find a list of both official and third-party add-on plugins that extend the functionality of the Shopkeepers plugin in the wiki: https://github.com/Shopkeepers/Shopkeepers-Wiki/wiki/Add-On-Plugins

If you have also written an add-on plugin that you want to add to the list, let me know!

Comments

blablubb
- Join Date: 5/29/2012
- Posts: 3,207
- Member Details
#2851 blablubb

View User Profile

Send Message

Posted Nov 12, 2017
In reply to huangwang:

I am not completely sure what you mean by "contrast position", but I assume you simply mean 'you have setup 2 separate trades'.

There are some minecraft specific behaviors you might run into here (things I cannot do much about):

If you insert items into the trading menu while you have selected the first trade, and the inserted items don't match the required items of the first trade, minecraft will search through the other trades for another matching trade-offer and then use this instead: Example, if the inserted items have lore which don't match the selected (first) trade, and there is another trade which would accept the inserted items, minecraft will allow you to trade according to the conditions of that other matching trade, without you having to explicitly select it in the trading menu. The only thing shopkeepers can do about this, is to manually check for perfect item equality, and if the items don't match, prevent the trade once you try to pickup the result items. There is a setting 'use-strict-item-comparison' for this, but I suggest not using it as it 'looks weird' to the players (because the result items still show up in the trading menu).

Another minecraft trading behavior: If your trade requires an item without any lore, minecraft will accept items with arbitrary lore. (Same goes for enchantments, etc., if I remember correctly). Basically, minecraft doesn't check for 'additional' item data when deciding whether the trade is accepted. You can use the 'strict-item-comparison' for this as well, if you really want to.
Rollback Post to Revision RollBack
liarrrrrrrr
- Location: Changsha
- Join Date: 2/1/2017
- Posts: 3
- Member Details
#2852 liarrrrrrrr

View User Profile

Send Message

Posted Nov 12, 2017
In reply to blablubbabc:

Thanks for your reply, I'm sorry for explaining it incorrectly, and I draw a picture to explain it in detail.

https://imgur.com/pACoJTT

Rollback Post to Revision RollBack
blablubb
- Join Date: 5/29/2012
- Posts: 3,207
- Member Details
#2853 blablubb

View User Profile

Send Message

Posted Nov 13, 2017
In reply to huangwang:

Okay, I was able to reproduce this. However, this seems to be a minecraft bug: I was able to reproduce it in vanilla minecraft by creating a custom villager with the /summon command containing this trade.

Unfortunely I wasn't able to find an open minecraft bug ticket about this yet. There is this (https://bugs.mojang.com/browse/MC-81687) which looks very similar, but it is slightly different and marked as fixed.

Maybe it might make sense to open a minecraft bug ticket there, in case there isn't one for this already.

Edit: Created a ticket: https://bugs.mojang.com/browse/MC-121932

Last edited by blablubb: Nov 13, 2017

Rollback Post to Revision RollBack
_ForgeUser21540602
- Join Date: 6/27/2019
- Posts: 0
- Member Details
#2849 _ForgeUser21540602

View User Profile

Send Message

Posted Nov 8, 2017
Awesome plugin! Can you update it to 1.12.2?

Rollback Post to Revision RollBack
_ForgeUser6837022
- Join Date: 5/19/2011
- Posts: 3
- Member Details
#2847 _ForgeUser6837022

View User Profile

Send Message

Posted Nov 6, 2017
Is it possible to disable Villagers trading mending books with this plugin?

Rollback Post to Revision RollBack
blablubb
- Join Date: 5/29/2012
- Posts: 3,207
- Member Details
#2848 blablubb

View User Profile

Send Message

Posted Nov 6, 2017
In reply to tomitytom:

Nope. You cannot rebalance vanilla villager trades with this plugin. You will have to look for another plugin to do that.

Rollback Post to Revision RollBack
stabbymeowkins
- Join Date: 8/30/2017
- Posts: 8
- Member Details
#2844 stabbymeowkins

View User Profile

Send Message

Posted Oct 31, 2017
Is there a way to disable villager trades, without disabling the cartographer, too? I wanted to disable trades from villagers on my server and exclusively have player shops and enchantment tables as means to get enchants etc(fishing for mending/frost walker)...

Sadly when I use this to disable villager trades, players can no longer obtain the treasure map in game for players to find the Mansions and Sea Temples.

Thank you very much for any help you give in regard to this manner.

Rollback Post to Revision RollBack
blablubb
- Join Date: 5/29/2012
- Posts: 3,207
- Member Details
#2845 blablubb

View User Profile

Send Message

Posted Oct 31, 2017
In reply to KnifeKat:

Nope, Shopkeepers can currently only block all non-shopkeeper villagers, or none. Your best bet is to not use Shopkeepers' feature and instead find someone to write you a small plugin which does exactly what you need: Blocking trades with all non-shopkeeper villagers, except cartographers.

Rollback Post to Revision RollBack
stabbymeowkins
- Join Date: 8/30/2017
- Posts: 8
- Member Details
#2846 stabbymeowkins

View User Profile

Send Message

Posted Nov 1, 2017
In reply to blablubbabc:

Thanks for the quick reply! I have opted to not worry and just using the /give command for the time being. If you ever would add this feature in the server, it would be what I'll use, and continue using since the same day it was released. I really like this plugin, and would prefer to never drop it at all. =P

If the feature never comes, I'll be sticking with the map give commands through achievements. =)

Much love, kisses and cake! :*

Rollback Post to Revision RollBack
blablubb
- Join Date: 5/29/2012
- Posts: 3,207
- Member Details
#2843 blablubb

View User Profile

Send Message

Posted Oct 26, 2017
Sorry for spam on github!

While automatically moving old issue tickets and comments from dev.bukkit.org to github, I initially forgot to remove all the @[username] tags from the messages. To everybody with a github account who received notifications due to this, SORRY!

I started noticing it only after the first 200 issues were already processed. I now removed all @ tags from the remaining 300 issues and comments, and hopefully trigger no more notifications for those.

Sorry again for the spam!

Edit: All issues have been moved over to github!

Please create new issues (or comments on existing issues) over there.

I will keep the issue tracker here on dev.bukkit.org open for another week or so, before I close it. So everybody has a chance to read my migration notices on all previously still open tickets.

Edit: The issues tab at the top now links to the issue tracker on github!

Last edited by blablubb: Nov 2, 2017

Rollback Post to Revision RollBack
blablubb
- Join Date: 5/29/2012
- Posts: 3,207
- Member Details
#2841 blablubb

View User Profile

Send Message

Posted Oct 23, 2017
Updated the front page and documentation!

The documentation can now be found in a wiki on github!

Let me know what you think!

Last edited by blablubb: Oct 23, 2017

Rollback Post to Revision RollBack
Forge_User_61403025
- Join Date: 10/22/2017
- Posts: 1
- Member Details
#2839 Forge_User_61403025

View User Profile

Send Message

Posted Oct 22, 2017
All my shopkeepers are gone :c

Can't really recall since when - last time I checked (19th) they were still there.

Rollback Post to Revision RollBack
blablubb
- Join Date: 5/29/2012
- Posts: 3,207
- Member Details
#2840 blablubb

View User Profile

Send Message

Posted Oct 22, 2017
In reply to Forge_User_61403025:

Check if the save.yml file is empty. If it isn't, maybe some plugin is blocking the shopkeepers from spawning. If it is empty, then shopkeepers might have not been able to properly save its data to the plugin folder. Make sure that the server process has write permission to the plugins folder and that no other process is interfering (ex. locking files).

Check all your server logs since when they were still there. If shopkeepers detects an issue during saving, it should log an error message.

Also check if there is a save.yml.temp file in the Shopkeepers folder. Shopkeepers will always first write to this temporary file, before removing the old existing save.yml file. So if something goes wrong during saving, the old save.yml should still be there. Only if everything worked out, it deletes the old save file and renames the temp file to the new save file.

Rollback Post to Revision RollBack
Forge_User_71149765
- Join Date: 10/17/2017
- Posts: 1
- Member Details
#2837 Forge_User_71149765

View User Profile

Send Message

Posted Oct 17, 2017
Can't edit Shopkeeper's inventory :/

I need some help :/

Rollback Post to Revision RollBack
blablubb
- Join Date: 5/29/2012
- Posts: 3,207
- Member Details
#2838 blablubb

View User Profile

Send Message

Posted Oct 17, 2017
In reply to Forge_User_71149765:

Create a ticket and explain step by step what you are doing, what you think you are doing, and what you see as result instead.

Rollback Post to Revision RollBack
danielgrainn
- Join Date: 8/1/2017
- Posts: 0
- Member Details
#2835 danielgrainn

View User Profile

Send Message

Posted Oct 11, 2017
The buyer doesnt work for 1.12

Rollback Post to Revision RollBack
DaDMaR777
- Join Date: 11/4/2012
- Posts: 23
- Member Details
#2833 DaDMaR777

View User Profile

Send Message

Posted Oct 9, 2017
Thank you ! for

Keeping Shopkeepers plugin alive !

Keep up the good work

Rollback Post to Revision RollBack
blablubb
- Join Date: 5/29/2012
- Posts: 3,207
- Member Details
#2830 blablubb

View User Profile

Send Message

Posted Oct 9, 2017
v1.83 for MC 1.12, 1.11, 1.10, 1.9, 1.8

Changed: Explicitly built with java 8 from now on.

Fixed / Reverted: If the display name / lore is empty in the config, the checked item's display name / lore is ignored again. Before it was required to be empty as well.

Fixed for MC 1.8.x: Custom pathfinder goals of shopkeepers being cleared instead of target goals.

Fixed: Skipping duplicate trades for the same item when loading shop.

Changed: Book shopkeepers now store their trades in a section called 'offers' (previous 'costs'), to be consistent with all the other shop types.

Minor internal refactoring related to shop offers handling for all shop types.

Fixed: Default config missing by-default enabled mob types for MC 1.12 (illusioner and parrot).

Fixed: Ejecting shopkeeper mobs right after spawning. Some entities have a random chance to mount nearby entities when spawned, ex. baby zombies on chickens.

Minor internal refactor related to applying mob sub-types for various living entity shops.

Added: Support for baby pigman shops. Previously pigman shops would randomly spawn as baby variant, now this can be explicitly specified in the editor menu of the shop.

Fixed / Re-Added: Ability to specify the required spawn egg type for the shop creation item in the config (default: villager). Can be set empty to accept any spawn egg type. Can be set to something invalid (ex. white space ' ') to only accept the spawn egg without any entity type assigned. This only works for the latest versions of bukkit 1.11 upwards! On MC 1.9 and 1.10 any spawn egg type will be accepted. On MC 1.8 the spawn egg type is specified via the data value.

Donations

If you like this plugin, consider making a donation.

Thanks in advance!
Last edited by blablubb: Oct 9, 2017

Rollback Post to Revision RollBack
malfoyesque
- Join Date: 10/9/2017
- Posts: 3
- Member Details
#2832 malfoyesque

View User Profile

Send Message

Posted Oct 9, 2017
Quote from blablubbabc >>

v1.83 for MC 1.12, 1.11, 1.10, 1.9, 1.8

Changed: Explicitly built with java 8 from now on.

Fixed / Reverted: If the display name / lore is empty in the config, the checked item's display name / lore is ignored again. Before it was required to be empty as well.

Fixed for MC 1.8.x: Custom pathfinder goals of shopkeepers being cleared instead of target goals.

Fixed: Skipping duplicate trades for the same item when loading shop.

Changed: Book shopkeepers now store their trades in a section called 'offers' (previous 'costs'), to be consistent with all the other shop types.

Minor internal refactoring related to shop offers handling for all shop types.

Fixed: Default config missing by-default enabled mob types for MC 1.12 (illusioner and parrot).

Fixed: Ejecting shopkeeper mobs right after spawning. Some entities have a random chance to mount nearby entities when spawned, ex. baby zombies on chickens.

Minor internal refactor related to applying mob sub-types for various living entity shops.

Added: Support for baby pigman shops. Previously pigman shops would randomly spawn as baby variant, now this can be explicitly specified in the editor menu of the shop.

Fixed / Re-Added: Ability to specify the required spawn egg type for the shop creation item in the config (default: villager). Can be set empty to accept any spawn egg type. Can be set to something invalid (ex. white space ' ') to only accept the spawn egg without any entity type assigned. This only works for the latest versions of bukkit 1.11 upwards! On MC 1.9 and 1.10 any spawn egg type will be accepted. On MC 1.8 the spawn egg type is specified via the data value.

Donations

If you like this plugin, consider making a donation.

Thanks in advance!

Such a quick fix! Thank you very much =)
Rollback Post to Revision RollBack
malfoyesque
- Join Date: 10/9/2017
- Posts: 3
- Member Details
#2827 malfoyesque

View User Profile

Send Message

Posted Oct 9, 2017
I have been trying to edit this part of the config to make it so that players must use a villager spawn egg to create a shop, but I can't seem to get it. How would I make it so that only villager spawn eggs work for player shops and not, for example, pig spawn eggs? (I've tried using the villager spawn egg ID)

shop-creation-item: MONSTER_EGG shop-creation-item-data: 0 shop-creation-item-name: "" shop-creation-item-lore: [] prevent-shop-creation-item-regular-usage: false deleting-player-shop-returns-creation-item: true

Thanks

Additionally, I've noticed that the pig_zombie shopkeeper seems to work perfectly well when first created, but it randomly changes to a baby pigman. The shopkeeper function works with the baby just fine, it just looks a little cuter. Great work on the plugin! The ghast shopkeeper is amazing.
Last edited by malfoyesque: Oct 9, 2017

Rollback Post to Revision RollBack
To post a comment, please login or register a new account.