Shop Guide

General Information

Shops are the main aspect of DisplayShops. These shops can be used to sell, purchase, obtain, give, or even take items.

Each shop works similarly to a vending machine, it has its own virtual balance which an owner or assistance can deposit alongside withdrawal from. In the main configuration (config.yml), the option "sync-owner-balance" can be enabled to automatically try and handle transactions from that particular player's vault balance. The sync option does NOT interfere with item-for-item by any means.

As a general note, when needing to disable a feature such as a sell or buy price, the value can be set to -1 to disable that particular numerical feature.

Shop Actions

The following are all actions that can be performed on a shop's base block:

Left-Click - If the player is the owner or an assistant, this action will open the shop edit menu. Otherwise, the shop transaction menu will be opened. If this action is performed on an admin shop and the player has access, then this will open the transaction menu.
Right-Click - If the player is the owner or an assistant, this action will open the edit menu. Otherwise, it will open the transaction menu.
Shift + Left-Click - If the held item is the exact same as the shop's unit item and permitted access, the player will deposit the stack of the unit item currently being held into the shop's stock.
Shift + Right-Click - If the shop is empty, this will take the item in the player's hand and set it as the shop's unit item. Otherwise, if permitted access, the player will withdraw the initial unit count from the shop per interaction.

Shop Creation

To create a shop, the shop creation item must first be obtained. The creation item can be obtained through the following methods:

/ds buy - Purchases a shop creation item from the server via command and charging the player the configurable price found in the configuration labeled as "creation-item-price". The user must also have the "displayshops.buy" permission to use this command.
/ds give {player} 1 - This command requires the permission "displayshops.give"; however, when {player} is replaced with the player's user name, they will obtain 1 shop creation item in their inventory or near their location if their inventory is full.

Once the player has a shop creation item, the next step is to simply place the item on the ground. This will then create a new shop that will request an item to complete the setup.

To complete the process, hold the item for sale in hand and SNEAK + RIGHT-CLICK the base-block of the shop to set a shop item. Keep in mind that the shop will take the full stack and use the entire stack as a single unit. This means that if a player sets 64 Oak Wood Planks as the shop item, a user can only purchase 64 per unit. This unit stack size can be adjusted through the edit menu.

To access the edit menu of a shop, a user must be an assistant or owner of the shop. As long as access is permitted to the user, the user can simply SNEAK + CLICK the base-block of the shop to open the management menu. Assistants will be able to do ANYTHING to the shop EXCEPT delete it. Owners of the shop or Admins are the only valid entities that have the ability to perform the delete action.

Item-For-Item Shops

As mentioned in the General Information section above, shops are similar to a vending machine which requires the owner to manage the balance manually by either depositing when the shop is low on funds or withdraw if it's reaching its limit.

Item-For-Item trading can be enabled by simply disabling Vault in the "config.yml" and then adjusting the default currency item alongside making the decision as to whether that item should be forced at all times. Forcing the item means that the shop's trade item (item wanted for the shop item) can NOT be adjusted by the player and will require that default currency item at ALL times. The amount requirement can still be adjusted, of course.

Nothing changes in terms of functionality aside that the owner or assistant of a shop must set the trade item alongside how much is required. Since this trade item could be anything, the preview item aka shop-item (the item being sold) can be interacted with to show the trade item until interacted with once more with the transaction interface used during the buying or selling actions.

Shop Customization (Per-Shop)

Each shop can be fully customized to its owner's style, needs, and wants. The most drastic customizable features include the base-block selection and description. Below please find all available customizable features found inside the shop's edit menu:

Balance Management - This option allows a suitable player to generally manage the shop's currency so that the shop has the ability to purchase items from the investor, similar to a vending machine's functionality. A suitable player must also withdraw currency from the balance every so often to keep the balance in check and prevent it from reaching the maximum value.
Base-Block Selection -* This option opens a secondary interface to allow a suitable player to adjust the visual base block of the shop, personalizing it and adding a bit of spice to its visual style!
Stock Management - This option works similarly to the balance management option; however, instead of a balance it is the full unit stock. This controls the number of items the shop has available to be purchased. Stocks are NOT UNLIMITED unless they are set through the command to -1 and are Admin Shops.
Limit Management - This option controls how many times players globally can purchase or sell from the shop. Setting either limit to -1 will disable the limitation feature.
Shop Item Management - This option handles the shop item alongside the trade item. The shop item is the item being sold by the shop in the form of units. A single unit is the EXACT same as the shop item, including stack size. The trade item is similar; however, this is considered as the currency the shop wants for the shop item-unit.
Price Management - This option is self-explanatory allowing modification toward the buy/sell price per unit. It also allows the toggling of Dynamic Prices, these simply raise the prices based on transaction popularity in a period of time. Dynamic Prices can also be manually reset.
Deletion - This option deletes the shop if the user has access to do so.

Admin Shops

Admin shops are a shop that has no owner, in short. To make an admin shop, a player must create a shop then look at it and run the /ds admin command to convert the shop to admin mode.

By default, admin shops DO NOT have unlimited stock. In order to make an admin shop have unlimited stock, the player must set the stock of the shop to -1 to ignore any stock limitations. Setting a stock to -1 will only work on Admin Shops. Use the command /ds stock -1 to update the stock value!

Admin shops also DO NOT have a balance limitation and DO NOT collect the balance from sales.

Market Regions

Market regions are rentable pre-set areas players can rent out and renew to gain access to whatever shops already exist within it. The system is left bare to allow easy extensions via configuration and/or API usage.

It is recommended to fill a region with shops before actually creating the region to avoid confusion on the instructions below.

To make a region, the command /ds sm must be used to enter selection mode. Similar to WorldEdit, the player must select a high and low point using the left and right-click actions to create a cuboid/rectangular selection. Once completed, the player must run the /ds cmr <region name> command to create the region.

Once the region is fully created, the player can either utilize the region's name or stand within the region while initiating the /ds rent <region> or /ds rent command. This will rent the region for that player, the player can utilize the same concept with /ds renew <region> and /ds renew to renew their region. To review the time left until their region expires, the player can utilize the /ds time <region> and /ds time commands. Admins can utilize the /ds reset <region> or /ds reset, if within the region, to reset its instance and wipe the region back to its standard form.

Hooks

Currently, PlotSquared and PlaceholderAPI are the only two plugins automatically hooked into by DisplayShops.

All PlaceholderAPI values are replaced in certain areas of the plugin, but some new existing PlaceholderAPI placeholders created by DisplayShops are:

Placeholder	Description
%displayshops_limit%	Gets how many functioning shops a player can have at one time. (Returns -1 if the player has no limit)
%displayshops_count%	Gets how many functioning shops a player currently has.
%displayshops_mrowner_{region}%	Gets the name of the renter where {region} is the market region name (If there is no renter, the placeholder will be replaced with "---").
%displayshops_mrtime_{region}%	Gets the remaining time until a market region expires where {region} is the market region name.