Shop

The shop is a set of categories, each holding products that the shop sells, buys back, or both. All of it is built in game from /shopadmin. There is no catalogue file: categories and products are database rows. modules/shop/config.yml only holds the settings that apply to the whole shop.

The module is the shop switch in config.yml, and like every switch it takes a restart. It needs an economy. Without one the plugin logs a warning at startup, and every purchase and sale is refused with "No economy is installed, so the shop is closed." Currencies, balances and Vault are covered in Economy.

Commands and permissions

Selling a single product from its category screen needs only exyliasurvivalcore.shop. The .sell node guards /sell, the sell window and the sell everything button.

The module adds no PlaceholderAPI placeholders. The %product_*% and %category_*% values in the menu files work only inside those menus, and each file lists its own values in its header.

Building the catalogue

/shopadmin opens the category list. The emerald creates a category: type an id, which is lowercased and can be up to 64 characters, and the category editor opens.

A category

Positions are chosen on a grid picker that has the front screen's shape: 21 buttons in rows of seven. Free positions are green. Taken ones are red and show the name of whatever holds them. Auto puts the category in the first gap. A category with no position, or one whose position is already taken, goes into the first free position on screen, and gaps left between placed categories stay empty.

On the text prompts for a description or a permission, clear or none removes the value.

The layout grid

Products opens a 54-slot grid. The top five rows are the category's 45 positions, slot for slot as players see them. The bottom row holds instructions, Back, and a command block.

• Put an item on a free slot and that slot becomes a product. The product is an exact copy of the stack on your cursor, including its name, lore, enchantments and count. Nothing is taken: the stack stays on your cursor.
• Click a product to open its editor.
• Shift-click a product, then click a free slot, to move it there. Clicking a taken slot cancels the move.
• The command block creates a product that runs commands instead of handing over an item, in the first free position. When all 45 positions are full it refuses.

The stack is the unit. If you drop 16 arrows, the product is sold and bought back 16 at a time, and the price is the price of those 16. When a player sells, their items are compared with the stored stack in every way except the count.

A new product has both prices switched off and is shown as not on sale until you give it at least one.

A product

The buy and sell buttons show two figures: the base price you set and the price right now, after pricing, discounts and your own sell bonus.

The example catalogue

When the shop starts and finds no categories and no products, it writes five categories with settings.example-catalogue on, which is the default:

Every price is a whole number in the default currency, and every product uses fixed pricing with no stock or limits. The prices follow two rules. A product sells back for about a third of its buy price. When one product can be crafted into another, the output never sells for more than its inputs. Gear, and anything crafted from materials the shop doesn't sell, is buy only. Edit or delete these like any other category.

Buying and selling

/shop opens the front screen: 21 category buttons with the player's balance in every currency. A category the player lacks the permission for is left out, or drawn behind iron bars when hide-locked-categories is false.

Inside a category, the way a product is drawn depends on what the viewer can do with it: buy and sell, buy only, sell only, a command, sold out, locked (no permission) or not on sale. If a product sells both ways and is sold out, it is shown as sell only, because the shop still buys it back.

On a sell-only product, both left and right click sell.

The amount screen has buttons for −64, −16, −1, +1, +16 and +64, plus ONE and MAX. MAX is the most the player can do right now. When buying, that is the lowest of max-amount, the stock, their remaining buy limit, what their balance covers, and how many units fit in their inventory. When selling, it is the lowest of max-amount, the units they carry and their remaining sell limit. CONFIRM only appears while the chosen amount is possible. A command product is always bought one at a time, and its amount buttons are hidden.

A purchase happens in a fixed order. The stock and the player's limit are reserved first. Then the money is taken. The items or commands are handed over last. If a step fails, the steps before it are undone. A purchase that won't fit in the inventory is refused before anything is charged. Room is counted across the storage slots and the hotbar.

A sale runs the other way round: the items leave the inventory first and the money arrives second. If the payment fails, the items come back.

The three ways to sell in bulk

• The sell window: the gold ingot on either shop screen (left click) or /sell. It has 45 slots. Put items in and close it to sell. Anything the shop doesn't buy comes back, and so does any leftover that doesn't make a whole unit. If there is no room for them, they are kept and delivered the next time the player joins. A reload that closes an open sell window completes the sale first.
• Sell everything: the gold ingot's right click or /sell all. It sells every product the shop buys back from the slots sell-all-scope covers, then reports one line per product and a total per currency.
• /sell hand: works out which product the held item is and sells as many units as that stack holds.

When an item matches more than one product, all three methods, and the sell wands, use the oldest enabled product in an enabled category.

Prices

A unit price is worked out in this order:

1. The base price you set.
2. Pricing changes it: fixed leaves it alone, by demand adds the current drift, and random applies the current draw. This step affects the buy price and the sell price equally.
3. Buy side: the larger of the product's discount and the category's discount is taken off. The two are not added together.
4. Sell side: the result is multiplied by the player's best exyliasurvivalcore.shop.sell.<multiplier> node and by any money booster that applies to shop-sell.
5. The price is rounded to the decimals of the product's currency.

The total for several units is rounded once, at the end.

Currencies

Every product has its own currency, and it is used for the price, the balance check and the payment. Different products in the same category can use different currencies, and a sell everything reports one total per currency. Any currency the economy knows can be picked, including the experience currencies once they are turned on. See Economy.

By demand

Every unit bought pushes the price up by step-percent of the base. Every unit sold back pushes it down by the same amount. The drift is kept between floor-percent and ceiling-percent of the base, and when nobody trades it moves back towards the base by decay-percent-per-hour percentage points each hour.

With the defaults, 10 units bought put a price of 100 at 110. After two hours with no trading it is back at 100. However much is traded, it stays between 50 and 200. Sales through sell wands and autosell move the price too. Switching a product's pricing mode resets its drift to zero.

The lore shows the drift as Trend: Stable, or a signed percentage.

Random

Each product gets a new random price every reset-hours, anywhere within spread-percent above or below its base. The draw depends only on the product and the period, so it is the same on every server and survives a restart. Periods are counted from midnight UTC, so with the default of 6 hours the prices change at 00:00, 06:00, 12:00 and 18:00 UTC. Trend shows how long until the next draw.

Discounts

A discount has a percentage from 0 to 100 and a duration of at least one minute (2d, 12h, …). Entering 0 removes it. A discount only lowers buy prices, and it ends by itself when its time is up. When both the product and its category have one, the larger applies.

Stock and limits

Stock is shared by every player. Buying takes units out. Selling back puts units in, up to the maximum. Setting the stock fills it to that number. When it reaches zero the product is drawn as sold out with a restock countdown, and a purchase is refused with the time left.

Restock refills the stock to its maximum. The interval is entered as a duration (30m, 6h, 0s for never) and stored in whole minutes. The countdown starts when you set it. The plugin checks once a minute. After a refill, the next one is due one interval later.

Limits apply to each player and each product. Buy and sell limits are counted separately, but they share one period of Limit period hours. The period starts at the player's first trade that counts. Once it has run out, both counts start again from zero at their next trade. A player who reaches a limit is told what the limit is and how long until it resets. A trade is only counted while its limit is set, so adding a limit later starts every player at zero. A player's counts are loaded when they join.

For a limit that covers the whole server, use stock.

Rotations

A category with Rotation on ignores product positions. It shows Products per rotation of its enabled products, drawn afresh every Rotation length hours and placed from the first slot. As with random prices, the draw depends only on the category and the period. It is the same on every server, periods are counted from midnight UTC, and nothing about it is stored. On the front screen a rotating category shows how long until the next draw.

Settings

modules/shop/config.yml:

Rotation size and length, stock, restock, limits and discounts are set per category or per product in the editor, not in this file.

Where it is kept

The sell window and the layout grid are plain inventories rather than menu files, so their layout can't be edited. See Database and Menus.

Other modules that use shop prices

• Sell wands and autosell sell only what the shop buys back, at the price the shop would pay that player, with a wand's own multiplier on top. They count against sell limits and move demand prices. The sell-wands module needs the shop enabled.
• Money boosters with the shop-sell source raise every shop sale, including sales through wands.
• The market adds Shop pays … each to a listing whose item the shop buys back. That figure is the price after pricing and before any player's bonus, divided down to a single item.

Sell wands and boosters are documented in Economy, and the market in Market.