#Overview
mcCoinShop is a menu-based store. Players open /coinshop, pick a category, choose an item and quantity on a confirm screen, and pay with one of your currencies. Everything can be edited in game with /mccs, or in plain YAML files.
- Currencies: unlimited built-in currencies (Coins, Tokens and Gems by default), plus any Vault economy and PlayerPoints.
- Categories and items: one file per category in
plugins/mcCoinShop/coinshop/, with items that can give physical items, run console commands or both. - Selling tools: sales, scheduled sales, coupons, daily deals, stock with restocking, purchase limits, cooldowns, dynamic prices, subscriptions, rank ladders and conditions.
- For players: gifting, a claim box, purchase history, search, subscriptions menu and vouchers.
- Earning: playtime, mob kills and a daily streak reward, with multipliers by permission.
#Installation
Requirements
- Paper 1.21.4 or newer (including 26.1), or a Paper fork.
- Java 21 or newer.
- No required dependencies. Vault, PlayerPoints and PlaceholderAPI are optional soft dependencies.
Install
- Put the jar in
plugins/and restart the server. - The plugin creates
plugins/mcCoinShop/withconfig.yml,messages.yml,sales.yml,coupons.yml,deals.yml,earning.yml,discord.yml, aguis/folder with the menus and acoinshop/folder with four example categories (ranks, weapons, blocks, cosmetics). - Run
/coinshopto see the default shop.
Upgrading from 1.x
Delete the old plugins/mcCoinShop/guis folder first so the new menus are created. Your config.yml layout stays close to 1.x and category files keep their format. Player balances and purchase counts import when each player next joins.
The example Ranks category runs LuckPerms commands such as lp user %player% parent add vip. Change them to your own rank plugin, or remove the items you do not want, before opening the shop to players.
#First steps
Open the shop
/coinshop opens the main menu. The command name and aliases come from general.command and general.aliases in config.yml (defaults: coinshop, cs, shop). Changing them needs /mccs reload. If another plugin already owns a name, the plugin cannot take it over, so pick a free name.
general:
# The shop command and its aliases. Needs /mccs reload.
command: "coinshop"
aliases:
- "cs"
- "shop"
date-format: "yyyy-MM-dd HH:mm"
Admin menu and editor
/mccs (also /mccoinshop) opens the admin menu with five buttons: Shop Editor, Currencies, Sales, Coupons and Reload. /mccs help lists every admin command. All of it needs coinshop.admin.
Give yourself currency
/mccs give YourName 1000
/mccs give YourName 50 gems
The currency defaults to economy.default-currency. Admin balance commands also work on offline players who have joined before.
OPs do not get the bypass permissions automatically, so limits, stock and cooldowns also apply to you. Use coinshop.free or the coinshop.bypass.* permissions only when you want to skip them.
#The in-game shop editor
/mccs editor opens the category list. Open a category to see its items, or click New Category to create a file in the coinshop folder.
- Click any item in your own inventory to sell it. The editor saves the exact item, including items from other plugins.
- For each item you can set the price, currency, name, lore, icon, stock, restock, limit, cooldown, subscription, dynamic pricing, permission and commands with clicks.
- Changes are written to the category file, so you can mix editing in game with editing the YAML.
The editor creates the category file, but the main menu only shows categories listed under category-items in guis/main.yml. Add a button there (see The main menu), or open the category directly with /coinshop open <category>.
#Categories and items
Every file in plugins/mcCoinShop/coinshop/ is a category. The file name is the category id, so ranks.yml is the category ranks. An item is referred to as category.item (for example ranks.vip) in commands, sales, coupons and placeholders.
Category settings
The gui section sets the title, the size and the filler:
gui:
title: "<gradient:#FFD76A:#FF9F43><bold>Ranks</bold></gradient>"
# auto fits the menu to its items and centers them. You can also use 27, 36, 45 or 54.
size: auto
fill-empty-slots: true
fill-item:
material: ORANGE_STAINED_GLASS_PANE
size: auto fits the menu to its items and centers them. You can also use 27, 36, 45 or 54. Items with no slot fill the menu by themselves, and more pages appear when needed. Price, stock and limit lines are added to the lore for you.
A simple item
Only display and price are required. This stack of cobblestone comes from the example Blocks category:
cobblestone:
display: {material: COBBLESTONE, name: "&7Cobblestone &8x64"}
price: {buy: 20, currency: coins}
item: {material: COBBLESTONE, quantity: 64}
display is the icon in the menu. item is what the player receives. They can differ.
An item with enchantments
iron_sword:
display:
material: IRON_SWORD
name: "&fIron Sword"
lore:
- "&7Sharpness II"
price:
buy: 250
currency: coins
item:
material: IRON_SWORD
enchants:
sharpness: 2
An item that runs commands
Items can run console commands instead of (or as well as) giving an item. %player% is the player who receives the item and %buyer% is the player who paid, which differs when the item is a gift.
vip:
display:
material: EMERALD
glow: true
name: "&a&lVIP"
lore:
- "&7Monthly rank."
- ""
- "&8• &7Join when the server is full"
- "&8• &7/fly"
- "&8• &710 homes"
price:
buy: 5000
currency: coins
commands:
- "lp user %player% parent add vip"
An item can also reward several items. Under item:, use an items: list of item sections instead of a single item.
All item options
Everything below goes under an item in coinshop/<category>.yml. See the Item options reference for the full table.
#Currencies
Currencies are defined under economy in config.yml. You can add as many as you like. Each built-in currency gets its own command as soon as you set command and run /mccs reload.
economy:
default-currency: coins
# How amounts look in messages and lore.
amount-format: "%color%%symbol% %amount% %name%"
# Number of players in /coins top.
top-size: 10
# Lets players turn currency into a voucher item with /coins withdraw <amount>.
player-vouchers: true
# Add as many currencies as you like. Each one gets its own command right away.
# Copy a block, change the id and the command, then run /mccs reload.
currencies:
coins:
enabled: true
display-name: "Coins"
symbol: "⛁"
color: "&6"
starting-balance: 100
command: "coins"
paying:
enabled: true
min-amount: 1
tax-percentage: 0
symbolandcolorare used byeconomy.amount-format(%color%%symbol% %amount% %name%).starting-balanceis what a new player starts with.payingcontrols/coinshop payand/<currency> pay.tax-percentageis charged on top of the amount: the sender pays the amount plus the tax, and the receiver gets the full amount.commandcreates a command such as/coins. Leave it blank for no command.
Add a currency
Copy one block under economy.currencies, change the id and the command, then run /mccs reload. In an item, use that id in price.currency. You can also create, edit and delete currencies in game from /mccs then Currencies: name, symbol, color, command, starting balance, payment rules and the default currency. Changes go live with no restart.
Vault and PlayerPoints
# Charge any Vault economy. Use "currency: vault" in an item's price.
vault:
enabled: true
display-name: "Money"
symbol: "$"
color: "&a"
command: ""
paying:
enabled: false
min-amount: 1
tax-percentage: 0
# Charge PlayerPoints. Use "currency: playerpoints" in an item's price.
playerpoints:
enabled: true
display-name: "Points"
symbol: "⚡"
color: "&e"
command: ""
paying:
enabled: false
min-amount: 1
tax-percentage: 0
Use currency: vault (or money) or currency: playerpoints (or points) in an item's price to charge those plugins. They need Vault with an economy plugin, or PlayerPoints, to be installed. Give them a command to get a balance command for them, and set paying.enabled: true to allow payments with the same tax rules.
/coins top only works for built-in currencies. For Vault and PlayerPoints use the economy plugin's own top list.
Currency commands
Each currency command works like this (replace coins with the command you set):
/coinsor/coins balance [player]shows a balance./coins pay <player> <amount>sends currency./coins topshows the richest players (size fromeconomy.top-size)./coins withdraw <amount>turns currency into a voucher item./coins give|take|set <player> <amount>and/coins reset <player>are admin commands (needcoinshop.admin).
Vouchers
Players with coinshop.voucher can turn currency into an item with /coins withdraw <amount>, when economy.player-vouchers is on. Right-clicking redeems it. Each voucher works once, so copies are worthless. Admins can hand one out with /mccs voucher <player> <amount> [currency].
#Buying, gifts and the claim box
The confirm screen
When a player clicks an item, a confirm screen opens (when shop.confirm-purchases is on and the item does not set confirm: false). It has quantity buttons, a Reset button and a Buy The Most button. It shows what the player gets, the full price and the balance. A coupon can be entered there when shop.coupons-enabled is on.
Why a purchase can fail
- Not enough currency, or the currency does not exist.
- Out of stock (bypass:
coinshop.bypass.stock). - The per-player limit is reached (bypass:
coinshop.bypass.limit). - The item's cooldown has not passed (bypass:
coinshop.bypass.cooldown). - The item needs a permission, an earlier purchase or a condition the player does not meet.
- The item has a future
previewing.publish-date. - The player already has that subscription.
Stock only changes after payment succeeds. Players with coinshop.free get every item for free.
Gifting
/coinshop gift <player> opens the shop in gift mode (online or offline players, needs coinshop.gift). The buyer pays and the receiver gets the item. Set giftable: false on an item to hide it from gifting. In commands, %buyer% is the payer.
Claim box
Gifts and rewards that do not fit in an inventory wait in the claim box. Players open it with /coinshop claim, with a Claim All button that collects as much as fits. shop.full-inventory is QUEUE (keep it for the claim box) or DROP (drop it at the player's feet). With shop.claim-on-join: true, waiting gifts are handed over when the player joins.
History, search and subscriptions
/coinshop historylists past purchases (up togui.history-size)./coinshop search <text>finds items by name./coinshop subscriptionslets players see, cancel and resume subscriptions.
shop:
# Shows the confirm screen with quantity and coupon. Items can override this with "confirm: false".
confirm-purchases: true
coupons-enabled: true
# When a reward does not fit: QUEUE keeps it for /coinshop claim, DROP drops it at the player's feet.
full-inventory: QUEUE
# Hands over waiting gifts and rewards when a player joins.
claim-on-join: true
# Tells everyone in chat about each purchase.
announce-purchases: false
announce-restocks: true
# Webhook warning when stock falls to this number.
low-stock-warning: 5
sounds:
open-sound: ui.button.click
purchase-sound: entity.experience_orb.pickup
error-sound: entity.villager.no
sale-start: entity.player.levelup
sale-end: block.note_block.bass
sale-join: entity.experience_orb.pickup#Stock, limits and cooldowns
Stock
Stock is shared by all players. Turn it on per item:
stock:
enabled: true
max: 10
regenerate: true
regen-time: 1h
regen-amount: 1
regen-interval: 1h
regen-date: "2030-01-01"
With regenerate: true, restocking works like this (the file checks them in this order):
regen-date: when the date passes and the item is sold out, it is restocked tomax. Acceptsyyyy-MM-dd,yyyy-MM-dd HH:mmoryyyy-MM-dd HH:mm:ss.regen-time: how long after selling out the item returns to full stock.regen-intervalandregen-amount: addregen-amountto the stock every interval, up tomax. This applies when neither a date nor a regen time is set.
Restocks are announced in chat when shop.announce-restocks is on. A webhook warning is sent when stock falls to shop.low-stock-warning. Admins can change stock with /mccs stock set <category.item> <amount> or /mccs stock refill <category.item>.
Limits
limit:
enabled: true
max-purchases-per-player: 1
reset-every: 7d
A player can buy at most max-purchases-per-player. With reset-every the count resets after that time, which is useful for weekly kits.
Cooldown
cooldown: 10m is the time a player must wait before buying the same item again.
Time values use units such as 30s, 10m, 1h, 7d.
#Sales, coupons and deals
Item discount
A permanent discount on one item: sale: {enabled: true, discount: 10}. Use display_sale to give the item a different look while it is discounted.
Timed sales
Start a sale by hand with:
/mccs sale create <time> <percent> [items|all] [players]
items is a comma-separated list of category ids, item ids or category.item (use all for everything). players is a comma-separated list of names for a sale that only they get. Example: /mccs sale create 2h 25 blocks,ranks.vip. List sales with /mccs sale list and end one with /mccs sale delete <id>. You can also create sales from /mccs then Sales.
While a sale for everyone runs, a boss bar with a countdown is shown (sale-bossbar in config.yml), and the start and end are announced.
sale-bossbar:
enabled: true
color: YELLOW
text: "<gradient:#FFD76A:#FF9F43><bold>%percentage%% OFF</bold></gradient> &7%items% &8| &7ends in &e%time%"
Scheduled sales
sales.yml holds sales that start by themselves, such as a weekend sale or a happy hour. Both examples are off by default:
scheduled:
weekend:
enabled: false
days: [SATURDAY, SUNDAY]
time: "12:00"
duration: 6h
percentage: 20
items: []
happy-hour:
enabled: false
days: []
time: "20:00"
duration: 1h
percentage: 10
items: [blocks]
days empty means every day. time is 24-hour server time. items empty means everything.
Coupons
Players enter a coupon code on the confirm screen. Make coupons in coupons.yml, in the Coupons editor, or with a command:
/mccs coupon create <code> <20%|500> [expires-in|never] [max-uses] [per-player] [min-spend] [items]
A value ending in % is a percentage, anything else is a fixed amount. Example: /mccs coupon create SUMMER 20% 7d 100 1 500 blocks. Remove one with /mccs coupon delete <code> and view them with /mccs coupon list.
coupons:
WELCOME10:
percent: 10
amount: 0
expires: 0
max-uses: 0
max-per-player: 1
min-spend: 0
items: []
expiresin the file is a time in milliseconds (0 is never). The command and the editor work this out for you.max-usesis total uses for everyone.max-per-playeris per player. 0 means no limit.min-spendis the smallest purchase it works on.itemsempty means everything. Use category ids, item ids orcategory.item.
Disable coupons with shop.coupons-enabled: false.
Daily deals
Each day the shop picks random items at a random discount. Players see them with /coinshop deals or from the main menu. Settings are in deals.yml:
enabled: true
menu-title: "<gradient:#FFD76A:#FF9F43><bold>Daily Deals</bold></gradient>"
# 24-hour server time.
refresh-time: "00:00"
# How many deals to show, up to 7.
count: 4
discount:
min: 10
max: 40
# Tell players when new deals are picked.
announce: true
pool:
# Leave empty to use every category. Subscriptions are never picked.
categories: [weapons, blocks, cosmetics]
# Item ids or category.item to leave out.
exclude: []
count is how many deals (up to 7). Subscriptions are never picked. /mccs deals picks new deals right now.
Dynamic pricing
Prices that follow demand. Each purchase adds demand, and demand falls over time. The price is base * (1 + demand * multiplier), kept between min-price and max-price (multiples of the base price). Every decay-interval, the price falls by decay of the base price.
dynamic-pricing: {enabled: true, multiplier: 0.05, decay: 0.05, decay-interval: 1h, min-price: 1.0, max-price: 2.5}
Reset an item's price with /mccs price reset <category.item>.
#Subscriptions, ranks and conditions
Subscriptions
A subscription item charges again every interval until the player cancels or cannot pay:
subscription:
enabled: true
interval: 30d
# Runs on each renewal.
renew-commands: []
# Runs when the subscription ends.
decline-subscription-commands:
- "lp user %player% parent remove vip"
- The first purchase starts the subscription. Every
intervalthe player is charged again andrenew-commandsrun. - When the player cancels, or cannot pay, the subscription ends and
decline-subscription-commandsrun (for example to remove the rank). - If the player is offline when it ends, they get a note when they next join.
- Players manage subscriptions in
/coinshop subscriptions. Cancelling stops the renewal but keeps the item until the paid time runs out, and it can be resumed. - Subscriptions are checked every
subscription.check-interval-secondsseconds (default 60). They are saved indata/subscriptions.yml. - Renew and decline commands use
%player%(the player's name).
Rank ladders and conditions
requires:
items: [ranks.vip]
conditions: ["%player_level% >= 10"]
requires.items makes an item need an earlier purchase of those items. requires.conditions are comparisons that use >=, <=, >, <, == or !=. Numbers compare as numbers and anything else as text. PlaceholderAPI placeholders in conditions need PlaceholderAPI installed.
Permissions on items
permission: some.nodeneeds that node to buy.permission-mode: purchase(default) shows the item but blocks buying.permission-mode: viewhides the item from players without the permission.
Timed release
previewing: {enabled: true, publish-date: "2030-01-01 12:00:00"} shows the item but blocks buying until the date. Use an absolute date.
#Earning currency
Players earn currency from earning.yml. Each part can be turned off, and each uses a currency id. Run /mccs reload after editing.
Playtime
playtime:
enabled: true
interval: 15m
currency: coins
amount: 10
# Skips players who haven't moved since the last payment.
skip-afk: true
Mob kills
mobs:
enabled: true
currency: coins
# Paid for any mob not listed under rewards. 0 pays nothing.
default: 0
# Mobs from spawners pay nothing, which stops mob farms.
ignore-spawners: true
# Paying kills per player per hour. 0 = no limit.
max-per-hour: 100
rewards:
ZOMBIE: 1
SKELETON: 1
SPIDER: 1
CREEPER: 2
ENDERMAN: 3
BLAZE: 3
WITHER: 100
ENDER_DRAGON: 250
Mobs from spawners pay nothing when ignore-spawners is on. max-per-hour limits paid kills per player (0 for no limit).
Daily reward
daily:
enabled: true
currency: coins
base: 25
per-streak-day: 10
max-streak: 7
Players claim it with /coinshop daily or the Daily Reward button, and need coinshop.daily. The reward is base + (streak - 1) * per-streak-day, with the streak capped at max-streak. Missing a day resets the streak.
Multipliers
multipliers:
vip: 1.5
mvp: 2.0
Give a player coinshop.multiplier.<name> (for example coinshop.multiplier.vip) to multiply playtime, mob and daily rewards. The highest one counts.
These nodes are not declared in plugin.yml. On servers where operators get unlisted permissions by default, an OP may receive every multiplier. Check with your permissions plugin if that matters.
#Admin tools and reports
/mccs stats [days]: revenue per currency and your best sellers (default 7 days)./mccs history <player>: a player's 10 latest purchases with their purchase ids./mccs refund <id>: gives the currency back for a purchase. A purchase can only be refunded once. Items and commands are not undone, because the plugin cannot know how to./mccs resetall <currency>: resets every player to the starting balance. You must run it twice within 30 seconds to confirm. Built-in currencies only./mccs reload: reloads every file. Open menus close first so nobody buys from an old layout.
Webhook alerts
discord.yml posts shop events to a chat webhook. Paste a URL into webhook-url (or give each event its own webhook-url), then set enabled: true on the events you want. All are off by default. Events: purchase, gift, sale-start, sale-end, restock, low-stock, out-of-stock, price-change, payments and admin-payments.
events:
purchase:
enabled: false
color: "#34D399"
title: "New purchase"
description:
- "**{player}** bought **{quantity}x {item}**"
- "Paid {price} {currency}"
gift:
Each event has a title, a description list and a color, and uses placeholders such as {player}, {item}, {quantity}, {price}, {currency}, {receiver}, {percentage}, {items}, {time}, {stock}, {old_price}, {new_price}, {sender}, {amount}, {tax} and {admin} as shown in the file.
Text and sounds
messages.yml holds every message. Keys you delete fall back to the default. Colors: &a codes, &#RRGGBB hex and MiniMessage such as <gradient:#34D399:#8B5CF6> work in all text. Sounds are set under shop.sounds in config.yml.
Storage
Data is stored in SQLite by default. Use MySQL if you want a database server. Purchases always save right away, and the rest saves every auto-save-interval minutes. All database work runs off the main thread.
storage:
# SQLITE needs no setup. Use MYSQL to keep the data on a database server.
type: SQLITE
# Minutes between saves. Purchases always save right away.
auto-save-interval: 5
mysql:
host: localhost
port: 3306
database: mccoinshop
username: root
password: password
use-ssl: false
table-prefix: mccs_
Developer API
Other plugins can listen to ShopPurchaseEvent (can be cancelled, and the price can be changed) and ShopPostPurchaseEvent in com.technotypist.mccoinshop.api.
#Commands
The shop command is /coinshop with aliases /cs and /shop by default (set in config.yml). The admin command is /mccs (also /mccoinshop). Currency commands such as /coins, /tokens and /gems exist for every currency that has a command. All shop commands except balance need coinshop.access.
| Command | What it does | Permission |
|---|---|---|
| /coinshop [open] | Open the main menu. | coinshop.access |
| /coinshop open <category|deals|history|subscriptions|claim> | Open a specific menu. | coinshop.access |
| /coinshop help | List the player commands. | none |
| /coinshop balance [player] | Show your balances in every currency. Viewing another player needs the second permission. | coinshop.balance.others (for other players) |
| /coinshop pay <player> <amount> [currency] | Send currency. Uses the default currency when none is given. | coinshop.pay |
| /coinshop gift <player> | Buy items for another player, online or offline. | coinshop.gift |
| /coinshop history | Your purchase history. | coinshop.access |
| /coinshop subscriptions | See, cancel and resume subscriptions. Also /coinshop subs. | coinshop.access |
| /coinshop claim | Collect gifts and items that did not fit. | coinshop.access |
| /coinshop deals | Today's daily deals. | coinshop.access |
| /coinshop daily | Claim the daily reward. | coinshop.daily |
| /coinshop search <text> | Find items by name. | coinshop.access |
| /coins [balance] [player] | Your balance in that currency, or another player's. The command name comes from the currency. | coinshop.balance.others (for other players) |
| /coins pay <player> <amount> | Send that currency. | coinshop.pay |
| /coins top | Richest players (built-in currencies only). | none |
| /coins withdraw <amount> | Turn currency into a one-use voucher item. | coinshop.voucher |
| /coins give|take|set <player> <amount> | Change a balance, also for offline players. | coinshop.admin |
| /coins reset <player> | Set a balance back to the starting balance. | coinshop.admin |
| /mccs | Open the admin menu (prints help in the console). | coinshop.admin |
| /mccs help | List every admin command. | coinshop.admin |
| /mccs reload | Reload every file. Renames of the shop command and currency commands take effect. | coinshop.admin |
| /mccs editor | Open the in-game shop editor. | coinshop.admin |
| /mccs open <player> [category] | Open the shop for an online player. Good for NPCs. | coinshop.admin |
| /mccs sale create <time> <percent> [items|all] [players] | Start a sale. Time examples: 30m, 1h, 7d. | coinshop.admin |
| /mccs sale delete <id> | End a sale. | coinshop.admin |
| /mccs sale list | List running sales. | coinshop.admin |
| /mccs coupon create <code> <20%|500> [expires-in|never] [max-uses] [per-player] [min-spend] [items] | Create a coupon. | coinshop.admin |
| /mccs coupon delete <code> | Delete a coupon. | coinshop.admin |
| /mccs coupon list | List coupons with their uses. | coinshop.admin |
| /mccs give|take|set <player> <amount> [currency] | Change a balance, also for offline players. | coinshop.admin |
| /mccs reset <player> [currency] | Set a balance back to the starting balance. | coinshop.admin |
| /mccs resetall <currency> | Reset everyone to the starting balance. Run twice within 30 seconds to confirm. | coinshop.admin |
| /mccs stock set <category.item> <amount> | Set an item's stock. | coinshop.admin |
| /mccs stock refill <category.item> | Refill an item to its maximum stock. | coinshop.admin |
| /mccs price reset <category.item> | Reset dynamic pricing for an item. | coinshop.admin |
| /mccs voucher <player> <amount> [currency] | Give an online player a voucher item. | coinshop.admin |
| /mccs history <player> | A player's latest purchases with ids. | coinshop.admin |
| /mccs refund <purchase-id> | Give the currency back for a purchase. Only once per purchase. | coinshop.admin |
| /mccs stats [days] | Revenue and best sellers (default 7 days). | coinshop.admin |
| /mccs deals | Pick new daily deals now. | coinshop.admin |
#Permissions
Permissions come from plugin.yml. The bypass and free permissions are not given to operators, so OPs see the shop like players do.
| Permission | What it allows | Default |
|---|---|---|
| coinshop.* | Grants access, admin, gift, pay, balance.others, daily and voucher. | op |
| coinshop.access | Open the shop and use its menus. | everyone |
| coinshop.admin | Admin commands, the in-game editor and update notices. | op |
| coinshop.gift | Buy items for other players. | everyone |
| coinshop.pay | Send currency to other players. | everyone |
| coinshop.balance.others | See other players' balances. | op |
| coinshop.daily | Claim the daily reward. | everyone |
| coinshop.voucher | Withdraw currency into a voucher item. | everyone |
| coinshop.bypass.* | Grants all three bypass permissions. | nobody |
| coinshop.bypass.stock | Buy items that are out of stock. | nobody |
| coinshop.bypass.cooldown | Ignore purchase cooldowns. | nobody |
| coinshop.bypass.limit | Ignore per-player purchase limits. | nobody |
| coinshop.free | Get every item for free. | nobody |
| coinshop.multiplier.<name> | Earning multiplier named in earning.yml (for example vip or mvp). | nobody (not declared in plugin.yml) |
#Placeholders
These work in the plugin's own menus even without PlaceholderAPI, and anywhere else when PlaceholderAPI is installed. <currency> is a currency id such as coins. <category>_<item> uses the category id, an underscore and the item id.
The number style for PlaceholderAPI values is set with placeholderapi.number-format (FULL, SHORT or FORMATTED).
| Placeholder | Value |
|---|---|
| %coinshop_<currency>% | The player's balance, as a full number. |
| %coinshop_<currency>_formatted% | Balance with thousands separators, for example 1,000,000. |
| %coinshop_<currency>_short% | Balance in short form, for example 1.0M. |
| %coinshop_<currency>_symbol% | The currency symbol. |
| %coinshop_spent_<currency>% | Total the player has spent in that currency. |
| %coinshop_total_purchases% | Number of items the player has bought. |
| %coinshop_total_purchases_formatted% | The same with thousands separators. |
| %coinshop_daily_streak% | The player's daily reward streak. |
| %coinshop_deliveries% | Number of gifts and items waiting in the claim box. |
| %coinshop_sale_active% | Yes or No, whether a public sale is running. |
| %coinshop_sale_percentage% | Discount of the best public sale (0 when none). |
| %coinshop_sale_time% | Time left of the best public sale (N/A when none). |
| %coinshop_deals_next% | Time until the daily deals refresh. |
| %coinshop_stock_<category>_<item>% | Current stock of an item, or an infinity sign when stock is off. |
| %coinshop_price_<category>_<item>% | The player's current price for one of the item, with sales applied. |
#Item options
Everything here goes under an item in coinshop/<category>.yml. Only display and price are needed. Defaults are what the plugin uses when the option is missing.
| Setting | Default | What it does |
|---|---|---|
| display | required | The menu icon: material, name, lore, glow, and optionally custom-model-data or skull-owner. |
| display_sale | same as display | A different look while the item is on sale. |
| price.buy | 0 | The price. A price of 0 makes the item free. |
| price.currency | economy.default-currency | Currency id, or vault / playerpoints. |
| slot | automatic | Menu slot. Leave out to fill the menu by itself. |
| page | automatic | Menu page, or a comma-separated list. |
| item | none | What the player receives: material, quantity, enchants and name, or an items list for several rewards. |
| commands | [] | Console commands run on purchase. %player% is the receiver, %buyer% is the payer. |
| confirm | shop.confirm-purchases | Set false to skip the confirm screen for this item. |
| max-quantity | 64 | Most the player can buy at once. |
| giftable | true | Whether the item can be bought as a gift. |
| sale.enabled / sale.discount | false / 0 | A fixed percentage discount on this item. |
| stock.enabled | false | Turn on limited stock. |
| stock.max | 100 | Maximum stock. |
| stock.regenerate | false | Restock automatically. |
| stock.regen-amount | 10 | Stock added each regen-interval. |
| stock.regen-interval | 0 | Time between regen-amount top-ups. 0 for none. |
| stock.regen-time | 0 | Time after selling out before a full restock. |
| stock.regen-date | none | A date when a sold-out item is fully restocked. |
| limit.enabled | false | Turn on per-player purchase limits. |
| limit.max-purchases-per-player | 0 | Most a player can buy. |
| limit.reset-every | 0 | Time after which the player's count resets. 0 for never. |
| cooldown | 0 | Time before the same player can buy this item again. |
| subscription.enabled | false | Make the item a subscription. |
| subscription.interval | none | Time between charges, for example 30d. |
| subscription.renew-commands | [] | Console commands run on each renewal. |
| decline-subscription-commands | [] | Console commands run when the subscription ends. |
| permission | none | Permission node required to buy. |
| permission-mode | purchase | purchase blocks buying. view hides the item. |
| requires.items | [] | Items (category.item) the player must have bought before. |
| requires.conditions | [] | Comparisons such as "%player_level% >= 10". |
| dynamic-pricing.enabled | false | Turn on demand-based pricing. |
| dynamic-pricing.multiplier | 0.1 | How strongly demand raises the price. |
| dynamic-pricing.decay | 0.05 | How much of the base price the price falls by each decay-interval. |
| dynamic-pricing.decay-interval | 1h | How often the price falls. |
| dynamic-pricing.min-price / max-price | 0.5 / 2.0 | Lowest and highest price as multiples of the base price. |
| previewing.enabled / publish-date | false / none | Show the item but block buying until the date (yyyy-MM-dd HH:mm:ss). |
#Configuration
Settings are in config.yml. Other files: messages.yml (every message), sales.yml (scheduled sales), coupons.yml (coupon codes), deals.yml (daily deals), earning.yml (earning), discord.yml (webhooks), guis/ (menus) and coinshop/ (categories). Run /mccs reload after editing. Text uses &a codes, &#RRGGBB hex and MiniMessage.
| Setting | Default | What it does |
|---|---|---|
| storage.type | SQLITE | SQLITE or MYSQL. The mysql block holds host, port, database, username, password, use-ssl and table-prefix (mccs_). |
| storage.auto-save-interval | 5 | Minutes between saves. Purchases always save right away. |
| economy.default-currency | coins | The currency used when none is given. |
| economy.amount-format | %color%%symbol% %amount% %name% | How amounts look in messages and lore. |
| economy.top-size | 10 | Number of players in /coins top. |
| economy.player-vouchers | true | Allow /coins withdraw. |
| economy.currencies.<id> | coins, tokens, gems | enabled, display-name, symbol, color, starting-balance, command and paying (enabled, min-amount, tax-percentage). |
| economy.vault / economy.playerpoints | enabled | Display settings for the Vault and PlayerPoints currencies. |
| shop.confirm-purchases | true | Show the confirm screen with quantity and coupon. |
| shop.coupons-enabled | true | Allow coupon codes on the confirm screen. |
| shop.full-inventory | QUEUE | QUEUE keeps rewards for /coinshop claim, DROP drops them. |
| shop.claim-on-join | true | Hand over waiting gifts and rewards when a player joins. |
| shop.announce-purchases | false | Tell everyone in chat about each purchase. |
| shop.announce-restocks | true | Announce restocks. |
| shop.low-stock-warning | 5 | Webhook warning when stock falls to this number. |
| shop.sounds.* | see file | open-sound, purchase-sound, error-sound, sale-start, sale-end, sale-join. |
| sale-bossbar.enabled / color / text | true / YELLOW / see file | The boss bar shown during a sale for everyone. Placeholders: %percentage% %items% %time%. |
| gui.live-update-seconds | 1 | How often open menus update their timers. |
| gui.close-after-purchase | false | Close the menu after a purchase. |
| gui.history-size | 112 | Number of purchases in the history menu. |
| gui.insufficient-funds.restore-after | 3 | Seconds before the "cannot afford" display returns to normal. |
| placeholderapi.number-format | FORMATTED | FULL 1000000, SHORT 1.0M, FORMATTED 1,000,000. |
| general.command / aliases | coinshop / cs, shop | The shop command and its aliases. Needs /mccs reload. |
| general.date-format | yyyy-MM-dd HH:mm | Date format used in menus. |
| subscription.check-interval-seconds | 60 | How often subscriptions are checked. |
| updates.* | see Updating | enabled, check-on-startup, check-interval-hours, auto-download, notify, shared-token, resource-id. |
#Troubleshooting and FAQ
/coinshop or /shop does not open my shop.
Another plugin may own that command name. The plugin does not take over a name that another plugin already uses. Change general.command and general.aliases in config.yml and run /mccs reload. Players also need coinshop.access.
My new category does not show on the main menu.
Add a button for it under category-items in guis/main.yml with its slot. Until then it can be opened with /coinshop open <category>.
An item shows "Requirements not met" or is missing.
Check requires.items, requires.conditions and permission. With permission-mode: view the item is hidden from players who lack the permission. Conditions that use PlaceholderAPI placeholders need PlaceholderAPI installed.
I use "currency: vault" but the item cannot be bought.
Vault and an economy plugin must be installed, and economy.vault.enabled must be true. If the currency does not exist the item cannot be bought.
OPs cannot bypass stock or limits.
That is on purpose. The bypass permissions and coinshop.free are not given to operators. Give them with your permissions plugin to the people who need them.
A player's rank was not removed when their subscription ended.
Add the removal command to decline-subscription-commands on the item. It runs when the subscription ends: when the player cancels and the paid time runs out, or when a renewal payment fails.
Can I undo a purchase?
/mccs refund <id> gives the currency back. Find the id with /mccs history <player>. The item and any commands are not undone.
Items disappear when the inventory is full.
They should not. With shop.full-inventory: QUEUE they wait in /coinshop claim. With DROP they drop on the ground.
A price in a message looks wrong for a Vault currency.
Vault and PlayerPoints use their own balances. Use economy.vault.display-name, symbol and color to change how they look.
Changes to the YAML files do not show up.
Run /mccs reload. Changes made in the in-game editors apply right away.
#Updating
Manual update
Stop the server, replace the old jar in plugins/ with the new one and start again. Your files and data are kept. New updates settings are added to your config without changing your other settings.
Update checker
The plugin checks BuiltByBit for a newer version. It only runs on a copy that was downloaded from BuiltByBit. Other copies log that update checks are off. Nothing is sent except the request itself.
updates:
enabled: true
check-on-startup: true
check-interval-hours: 24
# Downloads the new jar into plugins/update. It is installed on the next restart.
# The current jar is copied to plugins/mcCoinShop/backup first.
auto-download: false
# Tells the console and players with coinshop.admin.
notify: true
# Leave these blank to use the built-in values.
shared-token: ""
resource-id: 79244
- The check runs shortly after startup (when
check-on-startupis on) and then everycheck-interval-hourshours. It runs off the main thread. - With
notify: true, the console and players withcoinshop.adminare told when a newer version is out, and admins see it again when they join. - With
auto-download: true, the plugin downloads the new jar, verifies it is mcCoinShop at the expected version, copies your current jar toplugins/mcCoinShop/backupand places the new one in the server's update folder (plugins/update). It installs on the next restart. The running jar is never touched. - Auto-download needs the license to have download rights for the new version. Otherwise you are told it cannot download it.
If auto-download was on, the previous jar is in plugins/mcCoinShop/backup. Put it back into plugins/ to return to the old version.