Frequently Asked Questions

Other Features

More Information

Some plugins add a dummy enchantment to items to produce a glowing effect. Depending on the loading order of plugins (which is mostly random, so you cannot rely on it to always be the same) this dummy enchantment cannot be loaded for the item stored inside the shopkeeper when the server restarts. This causes the item to lose this enchantment and it then no longer matches the passed items which still have this enchantment. To resolve this issue you will (unfortunately) need to avoid using this glowing effect.

The shop doesn't accept my head items!

On older server versions Shopkeepers might not support setting up trades that involve head items with custom textures, because of an bug inside Spigot, that would cause Shopkeepers' save data to become corrupt when attempting to save such an item. If you want to test whether your server versions supports those head items (on your own risk!), there is a config setting for that: skip-custom-head-saving

Another issue you might run into with head items though:
Head items might fetch updated texture information from Mojang's servers and then update their internal texture data of the item with that. If this causes your offered head item to no longer match the head item required by the shopkeeper, the shopkeeper might not accept your item for the trade.
See The trade's result item doesn't show up!

I can't take the item out of the trade result slot!

If the result item of the trade shows up, but you cannot pick it up, that could be caused by:

Shopkeeper might not be supporting all kinds of inventory clicks. Try to pick up the item with an ordinary left mouse click.
There might be a discrepancy between what the server and the client 'see': Make sure that your client's Minecraft version matches the server's version and that you are not using any mods.
Otherwise: Some plugins might be modifying outgoing/incoming communication between the client and the server (ex. protocol-compatibility plugins, or plugins that try to hide some otherwise visible item data from the players, ..). Try if you can reproduce this issue without other plugins on the server, and then figure out which other plugin is causing this issue.
If you have the setting use-strict-item-comparison enabled, the trade might get prevented because the required and the offered items are not perfectly matching. Minecraft is more lenient: It will allow the trade even if the offered item has additional data which the required item is missing. Unfortunately I cannot prevent the trade's result item to show up in this case, because the Minecraft client will always show the item when it believes that the trade should work (even though we prevent it due to this setting).

Turning debug mode on might provide additional information in the console log when the trade fails.

Can I setup trades that repair items (i.e. ignore the damage of items)?

Nope, I don't think you can.

The damage of a damageable item (tool or weapon) is stored in the item's data under the key Damage: <value>. In order to setup a trade that repairs items regardless of their current damage value, you would need to be able to specify that the trade shall ignore the damage value of the item.

The shopkeepers plugin follows the trading logic of vanilla villagers: If the item required by the trade contains a piece of data, the item offered by the player has to contain this data as well. If the required item does not specify a certain type of data, the player is allowed to offer any item regardless of whether or not it contains this data (unless you enabled use-strict-item-comparisons inside the config, in which case the data of the required and the offered items has to always perfectly match in all aspects).

So in order for the trade to ignore the damage value of the item (i.e. accept items with any damage value), you would have to setup the trade with an item that does not contain this Damage: <value> data. However, Minecraft seems to always add this damage data to damageable items, no matter its value. So even an undamaged item will always contain the data Damage: 0. I haven't found a way to remove this damage data from items. When attempting to remove it (for example via Minecraft's /data .. command), Minecraft always immediately re-adds it.

Why not diverge from the vanilla Minecraft trading logic and allow trades that would usually not be possible?

There are several benefits to sticking to vanilla's trading logic. One of them is certainly that it keeps the plugin simpler, and feature requests in check (which translates to less bugs, less feature-creep, less maintenance effort, more time to work on other things).

However, there are even technical difficulties that arise when one tries to diverge from the vanilla logic: The last time I checked, the client does some predictions on what items to show inside the trading menu. For example, if it thinks that the trade cannot take place, it clears the result slot. And on various occasions (for example whenever some item in one of the inventory slots is changed), it checks this again and updates the client-side GUI state accordingly.
The problem is, this client-side inventory updating is even done when the plugin manually sets the item inside the result slot on the server-side, and the server then informs the client about this inventory change. So it is quite tricky (if even possible) to override this client-side behavior (at least without faking the items that are sent to and shown (!) on the client, and manually maintaining this faked inventory state). So any deviations to the trading logic on the server side would at least result in client-side visual glitches (e.g. the result slot being empty, even though the plugin on the server-side would allow the trade to take place).

There are actually some cases in which Shopkeepers diverges from the vanilla trading logic. However, they all involve preventing a trade that would usually be allowed by Minecraft. And these deviations do indeed result in the mentioned visual glitch. But it is less severe to show the result item of a trade even if the trade cannot actually take place, compared to not showing it even though the trade could take place.

I am having issues with trading repairable items

Trades won't work if the item required by the shopkeeper and the item provided by the player have different damage values. It is not possible to setup trades that ignore the damage value. See also Can I setup trades that repair items.

Another issue could be that the item required by the shopkeeper has previously been repaired in an anvil. In vanilla Minecraft, it becomes increasingly more expensive to repair items. Minecraft keeps track of this repair cost by adding or modifying the item's internal RepairCost data whenever the item is repaired. If the item required by the shopkeeper has this RepairCost data, then the repair cost of any items provided by players will have to be the same.

If you want players to be able to trade with any item, regardless of their repair cost, then you have to setup the trade with an item that does not have this RepairCost data, i.e. with an item that has not yet been repaired before. If you don't have use-strict-item-comparison enabled inside the config (this is disabled by default), the shopkeeper will then ignore the repair cost of the items provided by players.

I cannot trade via shift click due to the player shop chest being full, even though it should be possible to store the items

Consider a trade of one item for one other item. When you shift click inside the trading interface to trade, for example, 64 items for 64 other items, you are actually trading 64 times one item for one other item, instead of trading once 64 items for 64 other items. So even though it might be possible to remove 64 items from the chest, thereby free up a slot, and then insert the traded 64 items, this is not what actually happens. Instead, the trading may fail because when removing only one item from the chest at a time there may not be enough space afterwards to place the one traded item.

Calculating up front how many items are going to be traded would actually be rather tricky. Also, trading one time 64 items for 64 items may not be equivalent to trading 64 times one item for one item, due to the following reasons:

The situation (trades, chest contents, etc.) may usually dynamically change in-between the individual trades.
Depending on other plugins or the shopkeeper itself, each trade may have other side effects (other than only exchanging the items). So it makes a difference whether or not these side effects take place 64 times or only once.
In vanilla Mineraft, if the initially used trading recipe becomes unavailable (for example due to its limit of trades being reached) but there are still other trading recipes for the same items, but possibly with different conditions / prices, these other trading recipes are used nevertheless. So some of these trades may actually take place with different prices. In order to stay as closely as possible to the vanilla trading behavior, the Shopkeepers plugin replicates this logic.

Colors don't seem to be working in the config! They turn into weird characters!

Try setting the file-encoding option in the config file to "UTF-8". And make sure that your config is encoded in UTF-8. You can for example use NotepadPlusPlus to see and edit a file's encoding.

I can't use color codes for shopkeeper names!

Every time a shopkeeper is renamed the new name gets 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 characters & and §. In order to allow colors for shopkeeper names you have to add these characters to the regular expression in the config. I.e. set name-regex: [A-Za-z0-9&§ ]{3,25}

Will you add support for currency plugins (integrate with Vault)?

No, sorry. The trading 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 one of the following plugins which dynamically convert between your server's virtual currency and an corresponding item representation:

How do I disable player shops?

There is no global config setting to disable the creation of player shops (yet). Depending on your configuration, players can create player shops either via command (if create-player-shop-with-command is enabled) or by using the configured shop-creation-item (a regular villager egg by default).

One option to prevent players from creating shops is to disable the create-player-shop-with-command setting and change the shop-creation-item to something unobtainable by your players. You could for example set the shop-creation-item to a villager egg with a specific name and lore. See the Configuration page regarding how to specify custom item data inside the config. As long as your players are not able to obtain the item and set the lore to the one specified inside the config (they are not able to do that in vanilla Minecraft), they should not be able to create shops. Note that you cannot change the shop-creation-item to 'nothing'. If you remove the setting, keep it empty, or set it to something invalid such as AIR, it will revert to its default villager egg type.

Your other option is to use a permissions plugin (eg. PermissionsEx, LuckPerms, etc.) or Bukkit's permissions.yml file and negate the permissions required to create player shops for your players. Since there are various types of player shops with individual permission nodes, you will have to negate all of them. See the wiki page on the available permission nodes regarding that.
However, the setup and configuration of permissions plugins varies, so I won't be able to help you with that. If you have issues setting up the permissions, your best bet is to ask for help inside the Spigot forums, the Discord server, or the authors of your chosen permissions plugin. Permissions plugins usually also provide a command to check for specific permissions and thereby let you verify whether your permissions configuration works as intended. Additionally, if the debug mode is enabled, the Shopkeepers plugin will log every failed permission check to the console log (successful permission checks won't be logged though).

How do I disable the shop creation with villager eggs?

There is no setting to disable the creation of player shops via the shop-creation-item (regular villager eggs by default). Instead you can either prevent players from creating player shops altogether, or change the shop-creation-item to something unobtainable by your players. See How do I disable player shops? for more info.

How do I allow players to use villager eggs like normal?

By default the Shopkeepers plugin uses regular villager eggs as its shop-creation-item. This item can be used by players to create their own shops. At the same time we disable most of the default behavior for these items, such as being able to spawn regular villagers with them.

There are some exceptions to this restriction though:

Players in creative mode are completely unaffected. They can't even use the item to create player shops with it.
If you disable the prevent-shop-creation-item-regular-usage setting inside the config, or if a player has the shopkeeper.bypass permission, they are able to use the item like normal when held within their off-hand slot.

So if you want to allow your players to use villager eggs to spawn regular villagers, you can either disable the prevent-shop-creation-item-regular-usage setting and let your players know that they can use the item from their off-hand, or you can change the shop-creation-item to something else inside the config. You could for example set the shop-creation-item to a villager egg with a specific name and lore. See the Configuration page regarding how to specify custom item data inside the config. Any regular villager eggs without this specific name and lore will then behave like normal villager eggs.

What are 'Villager levels'?

Villager shopkeepers have an option to change their 'Villager level' (now called 'badge color' to cause less confusion) inside their Shopkeeper editor. This 'Villager level' is a purely cosmetic property of the villager and has no other purpose (it only changes the badge color of the villager entity). See this image from the Minecraft Wiki: Villager Level Badges

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 you instead just rebalance, or let admins configure the trade options of regular villagers?

The goal of this plugin is to provide custom item based shops that use the villager trading interface and are easy to setup. Modifying the trading options and the progression of vanilla villagers is a different goal and therefore out of scope for this plugin.

Nevertheless, there is an editor for regular villagers built-in (https://github.com/Shopkeepers/Shopkeepers-Wiki/wiki/Editor-for-regular-villagers), with which you can modify the trades of specific regular villagers. But anything beyond the current capabilities (and limitations) of that editor is considered out of scope for this plugin.

In the past there have been other plugins that offered the rebalancing of villager trades, as well as configurable trade options. Examples:

However, some of these may be outdated by now.

Can I sell more than a single stack of items?

Nope. The Minecraft trading interface only supports a single result item stack. Changing editor and the trading interface to support multiple item stacks for the result is out of scope for this plugin.

If you want to trade 1 item for multiple stacks of another item, consider using an intermediate currency item. For example, instead of trying to sell 8 stacks of dirt for 1 diamond, sell 1 stack of dirt for 1 emerald and allow players to exchange 8 emeralds for 1 diamond (eg. in a central admin shopkeeper near the spawn or market area).

My server's timings report shows that Shopkeepers is using lots of my server's processing time!

Before giving you performance tips, there are a few aspects you might want to be aware of when interpreting the Shopkeepers timings:

Timings sometimes produce 'false positives', i.e. they sometimes arbitrarily attribute a performance impact to certain tasks even though there is none or even though the performance impact is caused by something completely different. So try to reproduce your timings.
If you are not using Spigot (but for example another server derivative, such as Paper), try if you can reproduce your timings with Spigot. Also try different plugin combinations. Also try removing the Shopkeepers plugin and see if this actually resolves any apparent performance issue.
A similar issue applies to any kinds of maximum timings, such as the ones shown by the /shopkeeper check command: It is quite likely for the server to occasionally perform a costly garbage collection, which is then reflected in the timing measurement as well. Depending on your server's memory and your garbage collector configuration, these garbage collections can take anywhere from a few milliseconds to several hundred milliseconds. So outliners in the maximum timings are to be expected, and actually quite likely to observe.
Timings only provide a very coarse overview on things affecting your server performance. Consider to also run a profiler such as Spark. Spark is a plugin which allows you to easily create profiler reports and share them with others similar to timing reports. It is likely to also be less affected by the issue of 'false positives' mentioned above.
Take a look at how often a slow task is actually getting run (PerTick and Count). If the task gets run very infrequently, its performance impact should not worry you too much. For example: Some tasks might only get run at the very beginning of the plugin starting (or when you reload the plugin). Other heavy tasks might get run every time the server saves your world data (which on its own is usually pretty slow already).
If the task in question is indeed getting run frequently, then it is problably one of the following things:
- 'LivingEntityAI' responsible for handling entity gravity and the look-at-nearby-players behavior.
  On previous versions, the plugin disabled most of the entity AI and then let Minecraft handle the remaining things. However, even then Minecraft would still perform some AI tasks in the background that are not required for shopkeeper entities: Villagers would for example periodically search for nearby villages, and even cause additional chunk loading by that.
  On the recent versions of Shopkeepers, the spawned shopkeeper mobs therefore have most of their Minecraft AI disabled by default. The LivingEntityAI task is responsible for retaining an absolute minimum of behavior for the shopkeeper entities, such as their gravity and their behavior of looking at nearby players. The performance impact of these activities should be a lot lower than that of naturally spawned Minecraft entities (we only run a subset of the regular mob activities, and we only perform these activities for shopkeepers in chunks around players). So with the Shopkeepers plugin handling some of the behavior of the shopkeeper entities, you should be able to observe a benefit to your server's overall performance (due to the decreased time Minecraft spends with entity ticking and other background tasks). But the consequence is that these activities are now measured as part of Shopkeepers timings, whereas previously they were 'hidden' inside of Minecraft's timings itself.
- 'WorldListener' reacting to chunk loads and spawning the corresponding shopkeepers.
  If you have chunks with many shopkeepers, those will naturally require more work to load. If this really impacts your server somehow, then you probably have excessive amounts of shopkeepers in a very small area. Try if you can reduce the number of shopkeepers in the affected area.
  Maybe instead of having one dense market area for all your players' shops, consider having several across the world and limit the amount of shops that players can create there, or let your players create shops more freely across the world. However, keep in mind that spreading your players also means increasing the amount of loaded chunks. So this involves balancing your server's overall average performance with potential peak performance issues you have with certain dense areas.
  You can also limit the amount of shops players can create in total via a config setting and permission nodes. So players are forced to remove unneeded shops again. And there is also a setting to automatically remove shops of players that haven't visited the server in a long time (though this comes with the drawback of an increased startup time).
- Sign shops reacting to block physic updates.
  Block physic updates happen quite frequently in Minecraft. The Shopkeepers plugin has to react to them in order to prevent sign shops from getting destroyed. If this is an issue on your server, consider reducing the number of block physic updates (for example detect and prevent rapidly and constantly running redstone clocks), or disable sign shops altogether in the config.
- Saving of shopkeeper data.
  By default the plugin saves the shopkeepers data every time a player edits a shopkeeper. If you have many players constantly interacting with shopkeepers, it might beneficial to save the shopkeeper data periodically in batches instead. There is a config setting to disable the instant saving.

General performance hints: Reducing numbers. Here is a link to a great blog article on that.

Try to reduce the number of loaded chunks and the chunk load frequency.
If you have lots of players constantly passing with high speeds through your world and you use a large view distance, you naturally get lots of chunk loading and unloading that needs to be processed. Always keep an eye on Minecraft features or plugins which might be causing additional chunk loads in areas with no players, or might prevent chunks from getting unloaded again. The more chunks there are currently loaded, the heavier is the impact of the periodic world saves as well.
Maybe consider moving your server's market area far enough away from your server's spawn, so that shopkeepers don't get unnecessarily loaded every time players join your server.
Try to reduce the number of entities.
Every loaded entity in Minecraft comes with a certain overhead. Even though Shopkeeper entities have most of their AI disabled, they have a certain overhead as well.

How can I create a successful economy?

Nisovin has actually put a bit of thought into this. You can read his 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: entity.hasMetadata("shopkeeper")

Can I see the source code?

Certainly, here it is.

I have a different question or issue!

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

Shopkeepers / Shopkeepers-Wiki Public