Creating Shops - Shopkeepers/Shopkeepers-Wiki GitHub Wiki

Shopkeepers supports different types of admin and player shops, which differ in how their trades are set up and where they get their supplies from.
And Shopkeepers supports a wide range of object types, which are the things that represent the shop in the world.

The default available admin shop types are: Only admin currently.
The default available player shop types are: selling, buying, trading, book.
The setup of the trades slightly differs for each shop type. See Admin Shop Setup and Player Shop Setup.

In order to create shops of a certain type, the player is required to have the permission node specific to that shop type. See the Permissions Page. However, it is rarely required to actually configure the permissions: By default, non-OP players have access to all player shop types. But to actually create player shops, they additionally require access to the shop-creation-item (see Creating Player Shops).

Object types are the things that represent the shop in the world, such as for example the villager entity by default.
The default available object types are: sign, hanging-sign, npc (alias citizen), or the mob name for all currently supported and enabled mob types.
The creation of sign and hanging-sign shops works exactly the same as the creation of shops that are represented by a mob. But instead of a new mob being spawned when the shop is created, a new sign is placed.

For each object type there is a permission node that a player needs to have in order to be able to create shops with that object type. See the Permissions Page. By default, players have access to all enabled mob types, as well as sign shops.
Additionally, each object type can be globally disabled inside the config. See the Configuration Page. Some object types might be disabled by default.

You can theoretically try to use any mob type as shopkeeper entity. However, not all mob 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 mob types are currently enabled by default.
If you want to try out (on your own risk) if another mob type works as shopkeeper entity, you will have to manually enable it inside the config. You can find a list of all available entity type names in Spigot's documentation (Note: This list contains the names of all entity types the server knows about, but Shopkeepers can only useliving entities / mobs currently).

Also, each of these enabled mob types can only be used if the player has the required permission node: shopkeeper.entity.<mobtype> (or shopkeeper.entity.* for access to all enabled mob types). Example: shopkeeper.entity.villager
By default, players are able to use all of the enabled mob types (permission shopkeeper.entity.*).

The AI of shopkeeper mobs is overwritten, so that it doesn't wander away, is invulnerable to damage and doesn't interfere with vanilla game mechanics. Shopkeepers are stationary: They don't move and are automatically respawned and teleported back to their original spawn location after a few seconds if they were somehow deleted or teleported, e.g. by another plugin.

Except for certain flying mobs (allay, bat, bee, chicken, blaze, ender dragon, ghast, happy ghast, parrot, phantom, vex, wither), the shopkeepers entities are affected by gravity and fall to the ground. This ensures that they don't float in midair even if they were placed 1-2 blocks above ground. However, if they end up further than that from their original spawn location, they periodically teleport back until their original spawn location is restored.
Shopkeeper mobs that are neither flying nor shulker cannot be placed in midair.

If you want to use other entity types, you might want to try out Shopkeeper's integration with the Citizens plugin! You can find more information about that here.

Admin shops have infinite supplies and can trade any items you want them to trade.

To create an admin shop, just use the command /shopkeeper [object type] while looking at a (non-chest) block. A shopkeeper is spawned at the block you are looking at.

For editing the shop and setting up trades see Editing Shops and Admin Shop Setup.

Player shops pull their supply from a chest.

In order to create a player shop, you will need to hold the shop-creation-item in your hand. By default, this is a villager spawn egg with display name &aShopkeeper (see the Configuration).

As an admin, you can give yourself this item by using the command /shopkeeper give. If you want to allow other players on the server to create their own shops, you will have to setup a mechanism for them to get access to this item. An easy solution is to setup an admin shop, for example around your spawn area, that sells the shop creation item to your players. Other possibilities could be to setup custom mob loot drops that drop the shop creation item, or to change the item inside the config to something that can be acquired in vanilla Minecraft.
Giving players access to the /shopkeeper give command directly is not recommended, because this command can also be abused, and is really only meant as an utility for admins (similar to Minecraft's own give command).

The /shopkeeper give command optionally accepts a shop-type and object-type argument: When specified, the created shop creation item will only spawn shopkeepers of the specified player shop type and/or object type. When a player tries to use the shop creation item with a predefined shop or object type, we still perform the usual shop and object type disabled and permission checks. I.e. shop creation items can become useless if the respective shop or object type gets disabled or the player misses or loses their permission to use it.
Internally, the shop type and shop object type ids are stored in the item's custom_data in PublicBukkitValues with the keys shopkeepers:shop_type and shopkeepers:object_type. In combination with the shopkeepers:shop_creation_item tag (see Configuration), you can also use third-party item editing plugins to create custom shop creation items that spawn specific types of shopkeepers.

When you hold the shop creation item in your hand, it will print the instructions on how to create a player shop in chat.

First, make sure that you are not aiming at any block. You can then right-click to cycle through the different player shop types (selling, buying, trading, book). You can also hold sneak while right-clicking to cycle through the shopkeeper object types (villager, sign, witch, ..).

Then, right click on a chest (or other type of supported container) to select it, and then right click on another block to place the shopkeeper at that location.

For editing and setting up the trades of the newly created shop, see Editing Shops and Player Shop Setup.

Players with the shopkeeper.create permission (default: op) can also create player shops by using the /shopkeeper [shop type] [object type] command while looking at a chest. This will make the shopkeeper spawn at the targeted side of the chest.

If you aim at a block that is not a chest (or other type of supported container) while executing this command, and you don't explicitly specify a shop type, the plugin will assume that you try to create an admin shop.

[shop type] and [object type] are optional. If not specified, then either your current selection (the one you made by right clicking with the shop-creation item in your hand), or the default will be used.

Newly created shopkeepers that fail to spawn, e.g. when placed in a protected region and bypass-spawn-blocking is disabled (see Configuration), are immediately deleted again.

We only automatically delete shopkeepers that fail to spawn immediately after creating them. We do not automatically delete shopkeepers that later fail to spawn, because this is potentially risky. However, each shopkeeper tracks if their last spawn attempt failed and during plugin startup we log a warning for each of them. As an admin, you can then either investigate those cases, or (not recommended) use the command /shopkeeper deleteUnspawnableShopkeepers (see Commands) or the config setting delete-unspawnable-shopkeepers (default: false) to automatically delete them.

Note: From brief testing, Citizens NPC shopkeepers seem to bypass region protection plugins like WorldGuard currently, since they don't call the usual Bukkit entity spawn events that WorldGuard listens to.