This plugin allows you to 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.
Installation and Configuration
Simply download the latest file and put it into your plugins folder. When the plugin first loads, it will create a config.yml file in the Shopkeepers folder. There are several configuration options you can customize. See the Configuration Options page for more information.
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, etc.) will not work with this plugin.
In case you want to run this plugin on MC 1.8: this plugin supports Spigots updated versions of CraftBukkit. Other CraftBukkit derivatives/forks for MC 1.8 are not supported.
Creating a Shopkeeper
To create an admin shopkeeper, just use the command /shopkeeper [object type] while looking at a block. A villager will be spawned at the block you are looking at.
To create a player shopkeeper, you will need a villager spawn egg (or whatever item is defined in the config file). You must not be in creative mode when creating a shopkeeper. First, you can right-click in air (not on a block) to cycle through the different shop types (normal, book, buying, and trading). You can also hold sneak while right-clicking to cycle through the shopkeeper types (villager, sign, witch, ..). Then, right click on a chest to select it, then right click on another block to place the shopkeeper at that location.
You can also create a player shopkeeper by using the /shopkeeper [shop type] [object type] command while looking at a chest, but this will make the shopkeeper stand on top of the chest.
If no shop type and no object type are specified in the command, then either your current selection (the one you made via right clicking with the creation item in hand) or the default will be used. Alternatively you can specify only [shop type], only [object type], or both.
Every shopkeeper villager's AI will be overwritten so it doesn't wander away, and it is invulnerable to damage. It will also teleport back to its spawn location after a few seconds if it gets bumped out of place.
The default available player shop types are: normal (alias sell), buy, trade, book.
Shop object types are the things which represent the shop in the world, ex. the villager entity by default.
The default available shop object types are: sign, citizen (alias npc), or the mob name for all currently supported mob types.
Setting Up Trades (Admin Shopkeepers)
To modify the shop's trades, right-click on the shopkeeper while sneaking. This will open a regular-looking chest inventory, but it has a couple special icons on the right.
Each column in the inventory represents a trade option. The top item is the first cost, the middle item is the second cost, and the bottom item is the item to sell. The top and bottom items are required, but the middle item (the second cost) is optional. You can simply drag your recipes into the inventory. You can input up to eight recipes on a shopkeeper.
Once you are done editing the trades, simply close the inventory window to save. Now just right click on the shopkeeper, and see the trades! It should work with any items, including enchanted items and written books.
To set the shop's name, click the anvil then type the name into the chat. You can cycle through the villager professions by clicking on the wool block. If you want to delete the shopkeeper, you can click on the bone in the bottom-right corner (be careful, there is no undo!).
Setting Up Costs (Player Shopkeepers)
First, the player will need to place items they wish to sell in the chest. In order to sell written books you must use the special book shopkeeper (in this case, you must put the written books you want to sell in the chest, then stock it with book & quill items).
Then, right-click on the villager while sneaking. This will open up the shopkeeper editor. The top row will show the various item types for sale from the chest. The bottom row will show the costs of those items. If no cost has been specified yet, there will be a slimeball. To modify the cost, left-click the emerald (or slimeball) to increase the cost, and right-click to decrease the cost. You can also hold shift while clicking to modify the cost by 10 at a time. You can adjust the item quantity in the same way, with left and right clicks.
Once the costs are all set up, just close the window to save. You can also click the anvil to rename the shopkeeper, click wool block to cycle through the villager professions, and click the fire to delete the shopkeeper.
When a player purchases an item from a player shopkeeper, the item in the chest will be removed and the emeralds used to purchase will be added. Due to limitations in the game, the trades will not update even when a player purchases the final stack of a certain item. However, if a player attempts to make a purchase when the chest is out, the trade will fail and the trade inventory window will close automatically.
For the special "buying" shopkeepers, you must place at least one of each type of item you want to buy in the chest, as well as plenty of currency. Then when you open the editor interface, it works the same except the items are on bottom and the currency is on top. A buying shopkeeper can only buy basic items, not enchanted items, books, or maps.
Available mob types
You can theoretically try to use any living entity type as shopkeeper entity. However, not all entity types will actually properly work: While some might only show some weird but harmless behavior, others might cause more serious issues to your server or save-data.
Therefore, only a small tested subset of the available living entity types are currently enabled by default.
If you want to try out (on your own risk) if another living entity type works as shop entity, you will have to manually enable it in the config.
Also each of those enabled mob types can only be used if the player has the needed permission node: shopkeeper.entity.<mobtype> (or shopkeeper.entity.* for access to all enabled mob types).
By default players are only able to create villager, witch or creeper shops (if those are not disabled).
For compatibility with older versions there exist alternative permission nodes for some mob types: shopkeeper.villager, shopkeeper.witch and shopkeeper.creeper
If you want to use other entity types you might want to try out shopkeeper's integration with the citizens plugin! See below for information on that.
There is experimental support for shopkeepers using citizens npcs (disabled by default).
The permission needed to create citizens player shops is: shopkeeper.citizen
You can create an admin citizens shopkeeper with the command /shopkeeper npc.
Alternatively there is a 'shopkeeper' trait which you can assign to already existing citizens, though creating the citizens with the above command is the recommended way of doing it.
Citizens admin shopkeepers will default to normal villagers as mob type. You will have to use the citizens commands to change the mob type of the npc.
Citizens player shopkeepers will automatically default to player-type npc's with the name of the shop owner. There is a configuration options which determines if player's are allowed to renamed those npc player shops (default: false).
Using the /shopkeepers help command will display the available commands. Commands for which a player doesn't have the needed permission get filtered out.
You can use the /shopkeepers reload command to reload the plugin. This will save any changes and reload the config file.
Use /shopkeepers debug to toggle debug mode. This allows you to see sometimes useful information in the console.
Also there is a /shopkeepers checkitem command, which prints debug information about the item in hand, and the item in the next slot.
Use /shopkeeper list [player|admin] [page] to list the players own shops (if no player / 'admin' is specified), the shops of a specified player or all admin shops. The shops are divided into pages.
Use /shopkeeper remove [player|all|admin] to remove the players own shops (if no player/'admin' is specified), the shops of a specified player, all player shops, or all admin shops. The command needs to be confirmed by the player via /shopkeeper confirm.
Use /shopkeepers transfer playername to transfer ownership of a shopkeeper to another player. You must use this command while looking at a chest owned by a shopkeeper.
Use /shopkeepers setTradePerm <shop-id> <tradePerm|-|?> to set, remove (-) or display (?) the trading permission for an admin shopkeeper specified by id, unique id, or name. This trading permission will be required when a player tries to trade with the affected shopkeepe, additionally to the general trade permission.
Use /shopkeepers setforhire to set a player shopkeeper for hire. Hold the hire cost in your hand, and look at a chest owned by a shopkeeper when you use this command. This will allow another player to pay the hire cost and gain ownership of that shopkeeper.
|shopkeeper.*||Includes all other permissions.||op-only|
|shopkeeper.admin||Create and modify admin shops.||op-only|
|shopkeeper.debug||Access to the debug command.||op-only|
|shopkeeper.bypass||Modify player shops that you do not own.||op-only|
|shopkeeper.reload||Use the /shopkeeper reload command.||op-only|
|shopkeeper.list.own||List the own player shops via command.||everyone|
|shopkeeper.list.others||List the shops of other players via command.||op-only|
|shopkeeper.list.admin||List all admin shops via command.||op-only|
|shopkeeper.remove.own||Remove the own player shops via command.||op-only|
|shopkeeper.remove.others||Remove the shops of other players via command.||op-only|
|shopkeeper.remove.all||Remove all players shops of all players at once via command.||op-only|
|shopkeeper.remove.admin||Remove all admin shops via command.||op-only|
|shopkeeper.remote||Remotely open admin shops via shop name.||op-only|
|shopkeeper.transfer||Transfer a shopkeeper to another player.||op-only|
|shopkeeper.settradeperm||Set the trade permissions for admin shopkeepers.||op-only|
|shopkeeper.setforhire||Sets a shopkeeper to be up for hire.||op-only|
|shopkeeper.help||Access to the help command.||everyone|
|shopkeeper.trade||Allows trading with shopkeepers.||everyone|
|shopkeeper.hire||Allows a player to hire a shopkeeper.||everyone|
|shopkeeper.player.normal||Create normal player shops.||everyone|
|shopkeeper.player.book||Create book-selling player shops.||everyone|
|shopkeeper.player.buy||Create buying player shops.||everyone|
|shopkeeper.player.trade||Create item trading player shops.||everyone|
|shopkeeper.player||All player shops.|
|shopkeeper.entity.<mobtype>||Create shopkeepers of the specified mob type|
|shopkeeper.entity.*||Create all types of mob shopkeepers.|
|shopkeeper.entity.villager||Create a villager shopkeeper.||everyone|
|shopkeeper.entity.witch||Create a witch shopkeeper.||everyone|
|shopkeeper.entity.creeper||Create a creeper shopkeeper.||everyone|
|shopkeeper.sign||Create a sign shopkeeper.||everyone|
|shopkeeper.maxshops.<option>||Check out the configuration options for this.||none|
A tutorial by KreatorB showing how to setup shops with the more recent versions
A tutorial showing how to setup the trading player-shopkeepers: https:www.youtube.com/watch?v=5E2lOQQ_mPQ
Frequently Asked Questions
Something's gone wrong! I have a problem! Will you please help me?
Submitting a ticket is the best way to get help or report a problem with the plugin. Please provide the version you are using of both Craftbukkit/Spigot and Shopkeepers, and thoroughly describe the problem you are having, including step-by-step instructions on how to reproduce the problem.
My shop isn't working! Why can't I buy stuff from my shop?
You cannot buy items from your own player shop. This restriction is in place to help reduce duplication bugs if and when they arise. It doesn't completely prevent them, but it helps keep them from being obvious.
A shop isn't working! I can't take the item out of the trade result slot!
The items offered for the trade probably don't match the required items. The plugin not only compares the item types but also additional internal data of the items like display names, lore, enchantments, data values / durability, attributes and all kinds of even more specific data for items like skulls, books, potions, fireworks, etc.
If you turn debug mode on you should get detailed information in the console log why certain trades failed.
Why don't colors seem to be working in the config? They seem to turn into weird characters!
You should try setting your file-encoding option in the config file. Set it to "UTF-8".
I can't use color codes for shopkeeper names!
Every time a shopkeeper is renamed the new name get validated first. The plugin uses a regular expression for this validation which you can find and edit in the config file. This regular expression specifies which characters can be used for the name and how long the name has to be at least and at maximum. By default this regular expression might not contain the color code character '&'. So in order to allow colors for shopkeeper names you have to add that character to the regular expression in the config.
Will you add support for currency plugins (integrate with Vault)?
No, sorry. The trade interface is really designed for item trades only. For example, the purchase item doesn't even show up until you've put in the item cost required. As an alternative, you could use another plugin to create some sort of bank, where you would buy and sell emeralds for virtual currency. In this way players could deposit and withdraw emeralds for shopping. You may also be interested in the plugin Gringotts or GoldIsMoney.
How can I get shopkeepers to spawn when some other plugin like WorldGuard blocks them?
You could first try if it works when you enable the setting 'bypass-spawn-blocking' in the shopkeeper config.
If that doesn't work you will have to search for a setting in the other plugin which allows disabling this spawn blocking.
WorldGuard for example has a configuration option to specify which mob types it blocks from spawning. The option is under mobs, called block-creature-spawn. If it is empty, you will need to add in all of the creature types you wish to block, making sure you leave out Villager. Another option is to set WorldGuard's block-plugin-spawning option (also under mobs) to false, but this may have other side effects.
Can I have more than eight trades on a shopkeeper?
I feel like eight trades is plenty to have on one shopkeeper, and that it would be best to set up multiple shopkeepers if you need to have more items for sale. However, if you insist, it is possible, just more work.
For player shopkeepers, it's actually fairly easy. The cost setup will show the first eight item types in the chest. So, just set up the costs for those items, then rearrange the items in the chest. You will then be able to set up the costs for the other items.
For admin shopkeepers, the only way is to modify the save.yml file and add the options manually. Please note that I do not support doing this. If you try to do this and mess up your save file, you'll have to fix it on your own. In my opinion, you shouldn't do this anyway. It is a lot more user-friendly to have multiple shopkeepers with various categories of items (probably indicated by nearby signs).
Can you instead just rebalance the regular villager trade options, or allow admins to configure what trades are possible with regular villagers?
There is another plugin that offers villager trade rebalancing as well as custom trade options, you can find it here: http://dev.bukkit.org/server-mods/rebalance-villagers/
Oh wise Nisovin, how can I create a successful economy?
I've actually put a bit of thought into this. You can read my opinions here.
I am a plugin developer: How can I check if a given entity is a shopkeeper?
Every shopkeeper entity should be tagged with the 'shopkeeper' metadata, so you can check for that.
Can I see the source code?
Certainly, here it is.
You can find all previously uploaded files together with their changelogs on the 'Files' page.
If you like this plugin, consider supporting its development by making a donation:
Thanks in advance!
Want to help? Looking for a documenter!
Hey! I am looking for someone who would be willing to actively get involved in the project.
Currently that would probably mostly mean helping me with keeping the documentation up-to-date / improving it, but if you have any ideas on how you can contribute to the project beyond that, let me know!
If you are interested, feel free to contact me via PM.
v1.81 for MC 1.11, 1.10, 1.9.x, 1.8.x
- Fix: Error when trying to save trading recipe of trading shopkeeper.
v1.80 for MC 1.11, 1.10, 1.9.x, 1.8.x
- Added: Settings for prefix and default trading window title.
- Change: When getting a recipe from admin shop editor window with no first item, we try to use the second item as first item instead of completely disregarding the recipe. Similar to how the trading shopkeeper handles this.
Internal refactoring and cleanup:
- Removed separate handling of villager AI. Their AI is now replaced in the same way as for any other living entity shop.
- Major change: Using new bukkit api for opening virtual merchant inventories and getting the used trading recipe. This is only available in the very latest version of bukkit for MC 1.11, so if you are already using Spigot 1.11, you need to update to the most recent version.
- Changes/Fixes: All empty itemstacks related to trading recipes should now be replaced with null everywhere (similar to the pre-1.11 behavior). This also means that trading recipes with empty second item should no longer save this as an item of type AIR, but instead omit this entry all together.
- Changes: More consistent handling of empty itemstacks everywhere in the code.
- Minor code cleanup at various places.
v1.79 for MC 1.11, 1.10, 1.9.x, 1.8.x
Update for MC 1.11:
- Minecraft represents the different variants of skeletons (stray, wither_skeleton) and zombies (zombie_villager) now in the form of different entity types. Shopkeepers using these variants get automatically converted to use the new mob types instead.
This however means that you cannot switch back to previous minecraft versions without loosing those converted shopkeepers.
And you will have to give all your players, which were previously able to create zombie or skeleton shopkeepers the required permission nodes for stray, wither_skeleton and zombie_villager, otherwise they won't be able to access/edit their shops after this conversion.
Also, if you are running on a minecraft version below MC 1.11, you can no longer cycle through the different zombie variants and skeleton variants and existing shopkeepers using those will fallback to normal zombies and skeletons.
- Added the new mobs from MC 1.11 (evoker, vex, vindicator). Llamas, sadly, act weirdly currently when clicked (same goes for all horse variants) and are therefore not included in the default list of enabled mob types. In case you are updating, you will have to let the plugin recreate this config entry (by removing the entry or the whole config) or manually add those new mobs in order to enable them.
- Added: Support for the green 'Nitwit' villager variant added in MC 1.11.
- Some minor changes related to handling empty inventory slots and itemstacks, especially when creating the trading recipes, were required.
- Added a bunch of old mobs, which seem to mostly work fine, to the by default enabled living shop types. Also reordered this list a bit (roughly: friendly mobs first, hostile and new mobs at the end).
- Added: Instead of cycling between normal and villager variant, zombie shopkeepers can now change to baby variant by clicking the spawn egg in the editor window.
- Change: No longer disabling other, normal villagers by default.
- Fix: Ignoring double left clicks in editor window when adjusting item amounts. Previously this would cause 2 fast left clicks to be counted as 3 left clicks.
- Fix: Also ignoring double clicks when cycle shopkeeper object variants in editor window.
- Fixed: The 'compatibility mode' fallback, which is run if no supported minecraft version is found, wasn't able to open the trading window for players.
If you like this plugin, consider supporting its development by making a donation.
Thanks in advance!
- If the trade for a written book fails players can sometimes still open and read the book if they close the shop and click the temporary fake book in their inventory fast enough. There is not much I can do about this..
- Server crashes and improper shutdowns might cause living non-citizens shopkeeper entities to duplicate sometimes.
- The 'always-show-nameplates' setting is no longer working on MC 1.8.
- Compatibility with older bukkit versions is untested. If you encounter any problems let me know and I will look into it.
- A bunch of entity types are only meant for experimental usage. They might cause all kinds of issues if used. See changelog of v1.50.
- In the latest MC 1.8.x versions default minecraft trading logic has slightly changed (and by that those of shopkeepers as well): if a trade requires an item with special data (like a custom name, etc.) minecraft is now only allowing this trade, if the offered item is perfectly matching, including all special item data and attributes.
- MC 1.9 has changed how the different spawn eggs are differentiated internally. All spawn eggs now have the data value 0 and there is no API in bukkit yet which would allow me to check which type of spawn egg a player is holding. In order to get the shop creation via item working for now, you will have to either change the data value of the shop creation item to 0 (which will however let ALL types of spawn eggs act like the creation item), or you change the creation item type all together.
- Shopkeepers using skeleton or zombie variants after updating to MC 1.11 or above can not be loaded again (will be lost) when switching back to a previous minecraft version.
- If you are running on a minecraft version below MC 1.11, you can no longer cycle through the different zombie variants and skeleton variants. Existing shopkeepers using those will fallback to normal zombies and skeletons.
|File Name||Release Type||Game Version||Downloads||Date|
|v1.81||Release||1.11||32,467||Nov 24, 2016|
|v1.80||Release||1.11||2,251||Nov 21, 2016|
|v1.79||Release||1.11||2,609||Nov 18, 2016|
|v1.78||Release||1.10||12,761||Oct 24, 2016|
|v1.77||Release||1.10||52,506||Jul 14, 2016|
|v1.76||Release||1.10||21,770||Jun 10, 2016|
|v1.75||Release||1.10||1,060||Jun 10, 2016|
|v1.74||Release||1.9||15,895||May 15, 2016|
|v1.73||Release||1.9||4,057||May 10, 2016|
|v1.72||Release||1.9||7,157||May 1, 2016|
|v1.71||Release||1.9||11,801||Apr 7, 2016|
|v1.70||Release||1.9||16,189||Mar 8, 2016|
|v1.69||Release||1.9||10,932||Mar 1, 2016|
|v1.68||Release||1.8||67,343||Dec 21, 2015|
|v1.67||Release||1.8||8,491||Nov 28, 2015|
|v1.66||Release||1.8||2,165||Nov 24, 2015|
|v1.65||Release||1.8||21,889||Oct 25, 2015|
|v1.64||Release||1.8||3,998||Oct 23, 2015|
|v1.63||Release||1.8||51,048||Jul 17, 2015|
|v1.62||Release||1.8||1,578||Jul 17, 2015|
|v1.61||Release||1.8||13,455||Jun 23, 2015|
|v1.60||Release||1.8||6,153||Jun 12, 2015|
|v1.59||Release||1.8||2,875||Jun 7, 2015|
|v1.58||Release||1.8||2,096||Jun 5, 2015|
|v1.55||Release||1.8||5,274||May 18, 2015|
|v1.54||Release||1.8||648||May 17, 2015|
|v1.53||Release||1.8||602||May 17, 2015|
|v1.52||Release||1.8||26,295||Mar 15, 2015|
|v1.51||Release||1.8||1,811||Mar 13, 2015|
|v1.50||Release||1.8||2,720||Mar 7, 2015|
|v1.49||Release||1.8||1,991||Mar 4, 2015|
|v1.48||Release||1.8||538||Mar 4, 2015|
|v1.47||Release||1.8||1,376||Mar 1, 2015|
|v1.46||Release||1.8||7,026||Feb 12, 2015|
|v1.45.1||Release||1.8||2,936||Feb 6, 2015|
|v1.45||Release||1.8||1,295||Feb 5, 2015|
|v1.44||Release||1.8||1,230||Feb 3, 2015|
|v1.43||Release||1.8.1||13,533||Jan 9, 2015|
|v1.42||Release||1.8.1||1,425||Jan 6, 2015|
|v1.41||Release||1.8.1||835||Jan 5, 2015|
|v1.40||Release||1.8.1||440||Jan 5, 2015|
|v1.39||Release||1.8.1||2,538||Dec 30, 2014|
|v1.38||Release||1.8.1||1,303||Dec 28, 2014|
|v1.37||Release||1.8.1||6,651||Dec 17, 2014|
|v1.36||Release||1.8.1||354||Dec 17, 2014|
|v1.35||Release||1.8.1||270||Dec 17, 2014|
|v1.34||Release||1.8.1||560||Dec 16, 2014|
|v1.33||Release||1.8.1||490||Dec 15, 2014|
|v1.32||Release||1.8.1||562||Dec 15, 2014|
|v1.31||Release||CB 1.7.9-R0.2||6,119||Dec 6, 2014|
|v1.30||Release||CB 1.7.9-R0.2||1,840||Dec 1, 2014|
|v1.29||Beta||CB 1.7.9-R0.2||741||Nov 28, 2014|
|v1.18||Release||CB 1.7.9-R0.1||69,741||Apr 14, 2014|
|v1.17.2||Release||1.7.4||24,133||Mar 25, 2014|
|v1.17.1||Release||1.7.4||8,034||Mar 11, 2014|
|v1.16||Release||1.7.4||15,942||Feb 8, 2014|
|v1.16-beta3||Beta||1.7.4||14,556||Jan 8, 2014|
|v1.16-beta2||Beta||CB 1.6.4-R2.0||9,884||Dec 9, 2013|
|v1.16-beta||Beta||CB 1.6.4-R2.0||2,247||Dec 2, 2013|
|v1.15.1||Release||1.6.2||50,517||Jul 19, 2013|
|v1.14.2||Beta||1.6.1||3,191||Jul 4, 2013|
|v1.14.1 (broken)||Beta||1.6.1||1,034||Jul 2, 2013|
|v1.13.4||Release||CB 1.5.2-R1.0||36,466||Jun 25, 2013|
|v1.13.3||Release||CB 1.5.2-R0.1||9,919||Jun 11, 2013|
|v1.13.2||Release||1.5.2||15,895||May 3, 2013|
|v1.13.1||Release||CB 1.5.1-R0.2||7,579||Apr 17, 2013|
|v1.13||Release||CB 1.5.1-R0.1||3,486||Apr 9, 2013|
|v1.12||Release||CB 1.5.1-R0.1||5,126||Mar 21, 2013|
|v1.11||Release||CB 1.4.7-R0.1||11,349||Jan 19, 2013|
|v1.10||Release||CB 1.4.6-R0.3||3,759||Dec 31, 2012|
|v1.9||Beta||CB 1.4.5-R0.1||2,960||Nov 20, 2012|
|v1.8||Release||CB 1.3.2-R2.0||5,474||Oct 25, 2012|
|v1.7.1||Release||CB 1.3.2-R0.2||3,700||Sep 26, 2012|
|v1.7||Release||CB 1.3.2-R0.1||539||Sep 25, 2012|
|v1.6.1||Release||CB 1.3.2-R0.1||4,063||Aug 31, 2012|
|v1.6 (broken)||Release||CB 1.3.2-R0.1||5,722||Aug 29, 2012|
|v1.5||Release||CB 1.3.1-R2.0||1,898||Aug 20, 2012|
|v1.4||Release||CB 1.3.1-R1.0||2,342||Aug 14, 2012|
|v1.3||Release||CB 1.3.1-R1.0||958||Aug 9, 2012|
|v1.2||Release||CB 1.3.1-R1.0||621||Aug 7, 2012|
|v1.1 (broken)||Release||1.3.1||405||Aug 6, 2012|
|v1.0||Release||1.3.1||739||Aug 5, 2012|