#Overview
mcShardShop is a physical shop. Items float on stands that you place in your world. The shop picks new items on a schedule (every X hours, daily or weekly), and each item can have limited stock, purchase limits, a rarity and a random discount. Players walk up to a stand and click it to buy. There is no shop menu to open.
- Stands are built from Minecraft's own display entities, so no hologram plugin is needed.
- Rotation chooses which catalog items are on sale, using rarities, weights, guaranteed slots and deals.
- Currency is the built-in Shards by default. You can switch to Vault or PlayerPoints with one line.
- Earning lets players get shards from playtime, mob kills, mining and a daily streak.
- Admin menu lets you manage items, stands, the rotation and settings without editing files.
#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 your server's
plugins/folder. - Restart the server. The plugin creates
plugins/mcShardShop/withconfig.yml,items.yml,earning.yml,messages.yml,menus.yml,holograms.ymlandwebhooks.yml. - The console prints a line such as
Ready: 18 items, 0 stands, rotation #1.when startup is done.
The plugin ships with 18 starter items, so the shop fills itself as soon as you place the first stand.
Upgrading from 1.x
Swap the jar and restart. DecentHolograms is no longer needed. Balances, displays, items and settings import by themselves on the first start, and your old files are kept in plugins/mcShardShop/v1-backup.
If the database cannot be opened (for example wrong MySQL details), the plugin logs the problem and turns itself off. Check the storage section of config.yml.
#Setting up your shop
You need three things in place: stands, a warp and (optionally) the info board. All of it is done in game with /shardshop admin commands, and all of it needs mcshardshop.admin.
1. Place stands
Stand on the block where an item should float and run:
/shardshop admin stand create
The stand is placed at the centre of your block and takes the first free slot number (1, 2, 3 and so on). Each stand shows one item, so the number of stands decides how many items are on sale. Adding or deleting a stand updates the shop and the info board right away.
From the console you can place a stand with coordinates: /shardshop admin stand create <world> <x> <y> <z>.
Other stand commands:
/shardshop admin stand listlists every stand with its id, slot and position./shardshop admin stand tp <id>teleports you to a stand./shardshop admin stand delete <id>removes a stand. Ids autocomplete.
2. Set the shop warp
Stand where players should arrive and run /shardshop admin setwarp. The location (world, coordinates, yaw and pitch) is saved under shop-warp in config.yml. Players then run /shardshop to go there. Without a warp, players are told that no warp is set.
3. Place the info board (optional)
Run /shardshop admin setboard. The board is placed 2 blocks above your position and shows the countdown to the next rotation, the schedule and how many items are still in stock. Remove it with /shardshop admin removeboard.
4. Choose your items
See Items and the catalog. Then run /shardshop admin rotate to rotate immediately and check how the stands look.
/shardshop admin warp <player> sends an online player to the shop. Use it from an NPC plugin or a command block.
#How players use it
Buying at a stand
A player looks at a stand and left or right clicks it (both work, using a hitbox around the stand). While they look at a stand, their own balance and how much more they need is shown above the hotbar. The click needs mcshardshop.use, which everyone has by default.
By default a confirm screen opens where the player picks a quantity and sees the total price and their balance after the purchase. Turn it off with purchase.require-confirmation: false to buy one item per click. The most a player can buy at once is limited by purchase.max-quantity, the remaining stock, their limits and what they can afford.
Why a purchase can be refused
- Not enough shards.
- The item is sold out, or the shop rotated while the screen was open.
- The player reached the item's per-rotation limit or lifetime limit (bypass:
mcshardshop.bypass.limit). - The item has a
permissionthe player lacks. - The purchase cooldown has not passed (bypass:
mcshardshop.bypass.cooldown). - The inventory is full and
purchase.full-inventoryisblock.
Full inventory
purchase.full-inventory controls what happens when items do not fit:
claim(default): the leftover items wait in the claim box. Players open it with/shardshop claim.drop: the leftovers drop at the player's feet.block: the purchase is refused.
Catalog and wishlist
/shardshop catalog shows everything the shop can sell, with a filter by rarity. Clicking an item adds or removes it from the player's wishlist. When a wished item appears in a rotation, the player is told, also when they join after being offline. Needs mcshardshop.catalog.
History and leaderboard
/shardshop history lists the player's purchases. /shards top opens a leaderboard menu with player heads, including offline players (built-in currency only).
Announcements
Items of a rarity with announce: true (Legendary by default) are announced to the server when bought, if purchase.announce-rare is on. When the last unit of an item is bought, the server is told if purchase.announce-sold-out is on. Rotations are announced with a chat message, title and sound when rotation.announce is on, and players get a one-line notice on join when messages.join-notice is on.
#Items and the catalog
The catalog is every item the shop is allowed to sell. Each rotation picks from it. There are two ways to manage it.
In game (recommended)
/shardshop adminopens the admin menu. Open Items, click any item in your own inventory to add it, then click it in the list to edit it./shardshop admin additem <price> [rarity]adds the item in your main hand. The rarity defaults to the last one listed inconfig.yml(Common by default). Prices accept5k,2.5k,1mand1b.
Items added in game keep everything, including data from other plugins. The item editor lets you change the name, description, price, rarity, chance, stock, player limit, lifetime limit, commands and permission, among others.
By hand in items.yml
The top of items.yml explains every option. This is the template from the file:
my_item:
material: DIAMOND_SWORD
amount: 1
enchants: {sharpness: 5}
custom-model-data: 0
display-name: "&bName"
description: "&7One line of text"
price: 1000
rarity: rare # from config.yml
weight: 10 # higher shows up more often inside its rarity
stock: 5 # shared by all players each rotation. -1 for unlimited
limit: 1 # per player each rotation. -1 for none
lifetime-limit: 1 # per player, ever. -1 for none
give-item: true # false for items that only run commands
commands: # run by the console. %player% %uuid% %quantity%
- "say %player% bought something"
always: false # stays on sale in every rotation
enabled: true
deals: true # false keeps it out of random discounts
permission: "" # needed to buy it
season: {from: "12-01", to: "12-31"} # only sold between these dates (month-day)
Run /shardshop admin reload after editing the file.
Selling ranks, keys and commands
Set give-item: false and list console commands. The item is then only a button that runs commands. The starter item xp_bundle does this:
xp_bundle:
material: EXPERIENCE_BOTTLE
display-name: "&b&lXP Bundle"
description: "&7Runs a command instead of giving this bottle."
price: 900
rarity: rare
give-item: false
limit: 3
commands:
- "xp add %player% 5 levels"
Commands run once for each unit bought, as the console. %quantity% is the total quantity of that purchase.
Always-on and seasonal items
always: truekeeps an item on sale in every rotation.season: {from: "12-01", to: "12-31"}limits an item to a date range (month-day).enabled: falsehides it without deleting it.deals: falsekeeps it out of random discounts.
Stock and limits
stockis shared by every player and resets each rotation.-1is unlimited.limitis per player each rotation.lifetime-limitis per player forever.
#Stands and the info board
Every stand shows its item, spinning and bobbing, with text above it. The text comes from holograms.yml and the visual settings from the stands and board sections of config.yml.
stands:
# Height of the item and the text above the stand's block.
item-height: 1.25
text-height: 2.0
item-scale: 0.9
text-width: 220
# How far away the text can be read, in blocks.
text-range: 24
# The small block under the item. Its look comes from the rarity.
base: true
spin: true
spin-degrees-per-second: 90
bob: true
glow: true
particles: true
# Items shrink and pop back as the new ones when the shop rotates.
reveal: true
- A stand shows the rarity glow, sparkle particle and base block set for the item's rarity.
- When an item sells out, the glow turns off and the text changes to SOLD OUT with a countdown to the next rotation.
- With
reveal: true, items shrink away and pop back as the new ones when the shop rotates, one stand after another. - Stand entities are never saved in the world, so a crash cannot leave copies behind. They come back when a chunk loads.
Changing the text
holograms.yml controls the lines above stands (stand.lines, stand.sold-out-lines, stand.empty-lines) and on the info board (board.lines). A line that only holds a placeholder is left out when it has no value. Stand placeholders are %rarity% %name% %description% %price_line% %stock_line% %countdown%. Board placeholders are %schedule% %countdown% %rotation% %left% %total%.
stand:
lines:
- "%rarity%"
- "%name%"
- "%description%"
- "%price_line%"
- "%stock_line%"
sold-out-lines:
- "%name%"
- "&c&lSOLD OUT"
- "&7Back in &f%countdown%"
Info board
Place it with /shardshop admin setboard. Its size comes from board.scale, board.width and board.background-alpha.
board:
scale: 1.5
width: 300
background-alpha: 96#Rarities
Rarities are listed in config.yml from most to least valuable. Menus and stands use this order. You can edit them, remove them or add your own.
name: display text (supports gradients).color: the glow outline colour.weight: how likely a slot picks this rarity compared to the others.guaranteed: this many items of the rarity are always in a rotation, when the catalog has them.glow: outline on the stand.particle: sparkle around the stand, for exampleend_rod. Blank for none.base: the block under the floating item.announce: tell the server when this rarity is on sale or bought.
rarities:
legendary:
name: "<gradient:#FFD24A:#FF7A18><bold>LEGENDARY</bold></gradient>"
color: "#FFB020"
weight: 5
guaranteed: 0
glow: true
particle: totem_of_undying
base: GOLD_BLOCK
announce: true
An item's own weight decides how often it appears inside its rarity.
#Rotation and deals
The rotation decides which catalog items are on the stands. It fills itself as soon as items or stands exist, and /shardshop admin rotate rotates immediately. The countdown carries on through a reload.
rotation:
# When false, the shop only changes with /shardshop admin rotate.
enabled: true
# interval: every X. daily: each day at a time. weekly: one day each week.
mode: interval
# interval mode. Examples: 12h, 3d, 1d12h
every: 7d
# daily and weekly modes. 24-hour clock.
time: "18:00"
# weekly mode.
day: FRIDAY
# Blank uses the server clock. Example: America/New_York
timezone: ""
# An item stays out of the shop for this many rotations, when there are enough other items.
avoid-repeats: 1
# Chat message, title and sound when the shop changes.
announce: true
# Warnings before a rotation.
warnings: [24h, 1h, 10m, 1m]
mode: intervalrotates everyevery(for example12h,3d,1d12h).mode: dailyrotates each day attime.mode: weeklyrotates ondayattime.timeuses a 24-hour clock.- Set
enabled: falseto rotate only by hand. An interval of 0 is also an off switch. timezonetakes names such asAmerica/New_York. Blank uses the server clock.avoid-repeatskeeps an item out of the shop for that many rotations, when there are enough other items.warningsare the times before a rotation when players are warned.
How items are chosen
Always-on items are placed first, then each rarity's guaranteed amount, then the remaining slots are filled by rarity weight and item weight. Items outside their season or marked enabled: false are skipped.
Deals
Each rotation, a random discount is applied to some items. Items with deals: false or no price are never picked. The percentage is kept between 1 and 90.
deals:
enabled: true
per-rotation: 1
min-percent: 10
max-percent: 30
Rotation editor
In /shardshop admin, open Rotation to see what is on sale, swap any item for another one, or rotate on the spot.
#Currency and vouchers
By default the shop uses its own currency, Shards. Starting balance, name, display format, maximum balance, payments and vouchers are in the currency section.
currency:
# SHARDS is the built-in currency. VAULT and PLAYERPOINTS charge those plugins instead.
provider: SHARDS
singular: Shard
plural: Shards
# How amounts look everywhere. Placeholders: %amount% %currency%
display-format: "&d%amount% %currency%"
# What new players start with.
starting-balance: 100
# -1 for no maximum.
max-balance: -1
pay:
enabled: true
min-amount: 1
# Percent taken from each payment. 0 for none.
tax-percent: 0
# /shards withdraw turns shards into an item that can be traded.
vouchers:
enabled: true
min-amount: 10
Using Vault or PlayerPoints
Set currency.provider to VAULT or PLAYERPOINTS and the shop charges that plugin instead. Any economy plugin that is registered with Vault works. If the chosen plugin is not available, the console warns and the plugin falls back to the built-in Shards.
- Vault balances are treated as whole numbers (fractions are rounded down).
- With Vault or PlayerPoints, earning, daily rewards, vouchers,
/shards give|take|setand payments all go through that plugin. - The leaderboard (
/shards top) andstarting-balanceandmax-balanceonly apply to the built-in Shards.
Paying other players
/shards pay <player> <amount> sends shards, also to offline players who have joined before. currency.pay.tax-percent is taken from each payment, and the receiver gets the amount minus tax. min-amount sets the smallest payment. Turn payments off with pay.enabled: false.
Vouchers
/shards withdraw <amount> turns shards into a voucher item (needs at least vouchers.min-amount and a free inventory slot). Right-clicking the voucher redeems it. Every voucher has a unique id that can only be redeemed once, so copies are worthless.
Admin changes
/shards give|take|set <player|*|**> <amount> and /shards reset <player|*|**> change balances. * means everyone online and ** means everyone who ever joined. Reset sets the balance to starting-balance. Amounts accept 5k, 2.5k, 1m and 1b.
Vote plugins and crates can pay with the console command shards give %player% 100.
#Earning shards
Players earn currency from four sources, all set in earning.yml. Each section can be turned off on its own. Run /shardshop admin reload after editing.
Playtime
playtime:
enabled: true
interval: 15m
amount: 10
# Players who have not moved since the last payment get nothing.
skip-afk: true
Players who have not moved since the last payment get nothing when skip-afk is on. The smallest interval is 1 minute.
Mob kills
mobs:
enabled: true
# Paid for mobs not listed below. 0 pays only for listed mobs.
default: 0
# Mobs from spawners pay nothing, so farms can't print shards.
ignore-spawners: true
# Paid kills per hour for each player. 0 for no cap.
max-per-hour: 120
rewards:
ZOMBIE: 1
SKELETON: 1
SPIDER: 1
CREEPER: 2
ENDERMAN: 3
WITHER_SKELETON: 5
BLAZE: 3
ENDER_DRAGON: 500
WITHER: 250
Mobs from spawners pay nothing when ignore-spawners is on. max-per-hour is the number of paid kills per player each hour (0 for no cap). Use any entity type name under rewards.
Mining
mining:
enabled: true
# Blocks mined with silk touch pay nothing.
ignore-silk-touch: true
# Paid blocks per hour for each player. 0 for no cap.
max-per-hour: 200
# Ores placed by players pay nothing.
rewards:
DIAMOND_ORE: 5
DEEPSLATE_DIAMOND_ORE: 5
EMERALD_ORE: 8
DEEPSLATE_EMERALD_ORE: 8
ANCIENT_DEBRIS: 15
Blocks mined with silk touch pay nothing, and neither do ores that a player placed (the plugin remembers placed ores per chunk).
Daily reward
daily:
enabled: true
base: 25
# Added for each day in a row, up to max-streak.
per-streak-day: 10
max-streak: 7
Players claim it with /shards daily. The reward is base + (streak - 1) * per-streak-day, with the streak capped at max-streak. Missing a day resets the streak to 1. Claiming works once per calendar day (server time).
Multipliers
multipliers:
vip: 1.5
mvp: 2.0
Give a player mcshardshop.multiplier.<name> (for example mcshardshop.multiplier.vip) and they earn that much more from playtime, mobs, mining and the daily reward. The highest multiplier counts.
The plugin only counts a multiplier when the node is set on purpose, so OPs do not receive them just for being OP. Grant them with your permissions plugin.
#Messages and menus
All text can be changed. messages.yml holds every message, title and update notice. menus.yml holds the look of player menus (titles, buttons, item lore, the voucher item). holograms.yml holds stand and board text.
- Colour codes:
&a, hex&#RRGGBBand MiniMessage such as<gradient:#FF55FF:#55FFFF>work in every text field. - Keys you delete from
messages.ymlfall back to the built-in text. - The
messagessection ofconfig.ymlturns titles, action bar messages, sounds and the join notice on or off. Thesoundssection sets each sound key. Leave a sound blank for silence. - Item and stand lines can use PlaceholderAPI placeholders when it is installed.
#Webhook alerts
webhooks.yml posts shop events to a chat webhook (Discord-style embeds). Paste a URL into webhook-url, or give each event its own webhook-url, then set enabled: true on the events you want. All three events are off by default.
rotation: placeholders{rotation} {items} {next}.purchase: placeholders{player} {item} {quantity} {price} {rarity}.sold-out: placeholders{item} {player}.
events:
rotation:
enabled: false
webhook-url: ""
title: "The shop has rotated"
# Placeholders: {rotation} {items} {next}
description:
- "{items}"
- "New items in {next}."
color: "#D946EF"
purchase:
enabled: false
Each event also takes title, description (a list of lines) and color. The top-level username and avatar-url set the poster's name and picture.
#Storage
Balances, purchase history, wishlists and claims are stored in SQLite by default (no setup). Switch to MySQL if your host gives you a database. All database work runs off the main thread, and data is saved every auto-save-minutes minutes and when the server stops.
storage:
type: SQLITE
auto-save-minutes: 5
mysql:
host: localhost
port: 3306
database: mcshardshop
username: root
password: ""
use-ssl: false
table-prefix: mss_
The table prefix is mss_ by default. If the database cannot be opened at startup, the plugin disables itself.
#Developer API
Other plugins can listen to two events in com.technotypist.mcshardshop.api:
ShardPurchaseEventfires before a purchase is charged. It can be cancelled, and its price can be changed.ShardRotationEventfires when the shop rotates.
#Commands
Player commands are /shardshop (aliases /sshop, /ss) and /shards (alias /shard). Admin commands need mcshardshop.admin. Amounts accept 5k, 2.5k, 1m and 1b.
| Command | What it does | Permission |
|---|---|---|
| /shardshop | Warp to the shop. | mcshardshop.warp |
| /shardshop catalog | Browse every item the shop can sell and manage your wishlist. Also works as /shardshop wishlist. | mcshardshop.catalog |
| /shardshop claim | Collect items that did not fit in your inventory. | none |
| /shardshop history | Your purchases. | none |
| /shardshop help | Show the player help. | none |
| /shards | Show your balance. Same as /shards bal. | mcshardshop.shards.balance |
| /shards bal <player> | Show another player's balance (works for offline players). | mcshardshop.shards.balance.others |
| /shards pay <player> <amount> | Send shards to a player, also offline. Tax and minimum come from config.yml. | mcshardshop.shards.pay |
| /shards top | Open the richest players leaderboard (built-in currency only). | mcshardshop.shards.top |
| /shards daily | Claim the daily reward and grow your streak. | mcshardshop.shards.daily |
| /shards withdraw <amount> | Turn shards into a one-use voucher item. | mcshardshop.shards.withdraw |
| /shards give|take|set <player|*|**> <amount> | Change balances. * is everyone online, ** is everyone who ever joined. /shards remove works as take. | mcshardshop.admin |
| /shards reset <player|*|**> | Set balances back to the starting balance. | mcshardshop.admin |
| /shardshop admin | Open the admin menu (also /shardshop admin menu). | mcshardshop.admin |
| /shardshop admin additem <price> [rarity] | Add the item in your main hand to the catalog. | mcshardshop.admin |
| /shardshop admin stand create [world x y z] | Place a stand at your position, or at the coordinates (usable from the console). | mcshardshop.admin |
| /shardshop admin stand list | List stands. | mcshardshop.admin |
| /shardshop admin stand delete <id> | Remove a stand. | mcshardshop.admin |
| /shardshop admin stand tp <id> | Teleport to a stand. | mcshardshop.admin |
| /shardshop admin rotate | Rotate the shop now. | mcshardshop.admin |
| /shardshop admin setwarp | Set the shop warp to your position. | mcshardshop.admin |
| /shardshop admin setboard | Place the info board above your position. | mcshardshop.admin |
| /shardshop admin removeboard | Remove the info board. | mcshardshop.admin |
| /shardshop admin warp <player> | Send an online player to the shop. Good for NPCs. | mcshardshop.admin |
| /shardshop admin stats [days] | Sales report for the last N days (default 7). | mcshardshop.admin |
| /shardshop admin history <player> | A player's latest purchases. | mcshardshop.admin |
| /shardshop admin give|take|set|reset <player|*|**> [amount] | Same as the /shards admin commands. | mcshardshop.admin |
| /shardshop admin reload | Reload every file. The rotation countdown and stock carry on. | mcshardshop.admin |
#Permissions
Permissions come from plugin.yml. Item-specific permissions are whatever you write in an item's permission option.
| Permission | What it allows | Default |
|---|---|---|
| mcshardshop.use | Buy from stands. | everyone |
| mcshardshop.warp | Use /shardshop to go to the shop. | everyone |
| mcshardshop.catalog | Browse the catalog and use the wishlist. | everyone |
| mcshardshop.shards.balance | Check your own balance. | everyone |
| mcshardshop.shards.balance.others | Check the balance of other players. | op |
| mcshardshop.shards.pay | Pay other players. | everyone |
| mcshardshop.shards.top | View the leaderboard. | everyone |
| mcshardshop.shards.daily | Claim the daily reward. | everyone |
| mcshardshop.shards.withdraw | Turn shards into a voucher item. | everyone |
| mcshardshop.multiplier.<name> | Earning multiplier named in earning.yml (for example vip or mvp). Must be set on purpose. | nobody |
| mcshardshop.bypass.limit | Ignore per-player purchase limits. | nobody |
| mcshardshop.bypass.cooldown | Ignore the cooldown between purchases. | nobody |
| mcshardshop.admin | All admin commands, the admin menu and update notices. | op |
#Placeholders
With PlaceholderAPI installed, these work anywhere as %mcshardshop_<name>%. <slot> is the number of a stand (1, 2, 3...). Rank lists refresh about once a minute. Player placeholders return nothing for unknown players.
| Placeholder | Value |
|---|---|
| %mcshardshop_balance% | The player's balance as a plain number. |
| %mcshardshop_balance_formatted% | Balance with commas, for example 1,500. |
| %mcshardshop_balance_short% | Balance in short form, for example 1.5k. |
| %mcshardshop_currency_singular% | The singular currency name (Shard). |
| %mcshardshop_currency_plural% | The plural currency name (Shards). |
| %mcshardshop_next_rotation% | Countdown to the next rotation. |
| %mcshardshop_rotation_interval% | The rotation schedule as text. |
| %mcshardshop_rotation_number% | The current rotation number. |
| %mcshardshop_items_left% | How many stands still have stock. |
| %mcshardshop_daily_streak% | The player's daily reward streak. |
| %mcshardshop_total_spent% | Total the player has spent in the shop. |
| %mcshardshop_total_purchases% | Total items the player bought. |
| %mcshardshop_wishlist% | Number of items on the player's wishlist. |
| %mcshardshop_claims% | Number of items waiting in the claim box. |
| %mcshardshop_offer_<slot>_name% | Name of the item on that stand. |
| %mcshardshop_offer_<slot>_price% | Current price on that stand, with any deal applied. |
| %mcshardshop_offer_<slot>_stock% | Stock left on that stand, or an infinity sign when unlimited. |
| %mcshardshop_offer_<slot>_rarity% | Rarity name of the item on that stand. |
| %mcshardshop_offer_<slot>_discount% | Deal percentage on that stand (0 when none). |
| %mcshardshop_top_<rank>_name% | Name of the player at that leaderboard rank (top 10, built-in currency). |
| %mcshardshop_top_<rank>_balance% | Balance of the player at that leaderboard rank. |
#Configuration
Every option in config.yml works as described. Most of them can also be changed in game from /shardshop admin. Run /shardshop admin reload after editing a file.
Other files
items.yml: the catalog.earning.yml: playtime, mobs, mining, daily reward and multipliers.messages.yml,menus.yml,holograms.yml: all text and player menus.webhooks.yml: alerts for rotations, purchases and sold-out items.
config.yml options
| Setting | Default | What it does |
|---|---|---|
| updates.enabled | true | Turn the BuiltByBit update check on or off. |
| updates.check-on-startup | true | Check shortly after the server starts. |
| updates.check-interval-hours | 24 | Hours between checks, from 1 to 168. |
| updates.auto-download | false | Download new versions by themselves. They install on the next restart. |
| updates.notify | true | Tell the console and admins about updates. |
| updates.shared-token / resource-id | "" / 0 | Leave blank to use the built-in values. |
| gui.live-update-seconds | 1 | How often open menus redraw their timers. |
| storage.type | SQLITE | SQLITE or MYSQL. See the mysql block for host, port, database, username, password, use-ssl and table-prefix. |
| storage.auto-save-minutes | 5 | Minutes between automatic saves. |
| currency.provider | SHARDS | SHARDS, VAULT or PLAYERPOINTS. |
| currency.singular / plural | Shard / Shards | Currency names. |
| currency.display-format | &d%amount% %currency% | How amounts look everywhere. Placeholders: %amount% %currency%. |
| currency.starting-balance | 100 | What new players start with (built-in currency). |
| currency.max-balance | -1 | Highest balance. -1 for no maximum. |
| currency.pay.enabled / min-amount / tax-percent | true / 1 / 0 | Player payments, the smallest payment, and the percent taken from each payment. |
| currency.vouchers.enabled / min-amount | true / 10 | Allow /shards withdraw and set the smallest voucher. |
| rotation.enabled | true | When false, the shop only changes with /shardshop admin rotate. |
| rotation.mode | interval | interval, daily or weekly. |
| rotation.every | 7d | Interval mode length, for example 12h, 3d, 1d12h. |
| rotation.time / day | "18:00" / FRIDAY | Time (24-hour) for daily and weekly modes, and the day for weekly mode. |
| rotation.timezone | "" | Time zone name such as America/New_York. Blank uses the server clock. |
| rotation.avoid-repeats | 1 | Rotations an item stays out of the shop, when there are enough other items. |
| rotation.announce | true | Chat message, title and sound when the shop changes. |
| rotation.warnings | [24h, 1h, 10m, 1m] | Warnings before a rotation. |
| deals.enabled / per-rotation | true / 1 | Random discounts, and how many items get one each rotation. |
| deals.min-percent / max-percent | 10 / 30 | Range of the random discount. |
| rarities.<id> | 4 defaults | name, color, weight, guaranteed, glow, particle, base and announce for each rarity. |
| purchase.require-confirmation | true | Show the quantity and price screen before buying. |
| purchase.max-quantity | 64 | The most a player can buy in one go. |
| purchase.cooldown-seconds | 2 | Seconds between purchases. 0 for none. |
| purchase.full-inventory | claim | claim, drop or block. |
| purchase.announce-rare / announce-sold-out | true / true | Tell the server about announce rarities being bought and about sold-out items. |
| messages.enable-titles / enable-actionbar / enable-sounds / join-notice | true | Turn feedback types on or off. |
| sounds.<key> | see file | Sound keys for menu-open, click, purchase, fail, rotation, warning, reveal, wishlist and earn. Blank for silence. |
| stands.* | see file | item-height, text-height, item-scale, text-width, text-range, base, spin, spin-degrees-per-second, bob, glow, particles, reveal. |
| board.scale / width / background-alpha | 1.5 / 300 / 96 | Info board size and background. |
| shop-warp.* | empty | Warp location. Set it with /shardshop admin setwarp. |
#Troubleshooting and FAQ
Players are told that no shop warp is set.
Stand where players should arrive and run /shardshop admin setwarp. The warp world must be loaded.
Stands show "Nothing here" or are empty.
A stand shows nothing when the shop has no item for its slot. Make sure the catalog has enabled items (inside their season) and run /shardshop admin rotate. If you have more stands than items, the extra stands stay empty.
I cannot see a stand after restarting.
Stand entities are never saved in the world and are recreated when the chunk loads. Walk near it. If it is still missing, check /shardshop admin stand list that the world name is right and the world is loaded.
Clicking a stand does nothing.
Check the player has mcshardshop.use. Remember the purchase cooldown (purchase.cooldown-seconds) and that a sold-out stand only shows a message.
I set currency.provider to VAULT but shards are still used.
Vault must be installed and an economy plugin must be registered with it. If it is not available, the console prints a warning and the plugin uses the built-in Shards.
/shards top says the leaderboard is not available.
The leaderboard only exists for the built-in Shards currency. With Vault or PlayerPoints, use the economy plugin's own top list.
/shards give says the player was not found.
The name must belong to a player who has joined the server before (or is online). It does not give shards to names that never joined.
Items go to the claim box instead of my inventory.
That is purchase.full-inventory: claim. Change it to drop or block, or tell players to use /shardshop claim.
The plugin turned itself off at startup.
It could not open the database. Read the console lines above the shutdown. For MySQL, check host, port, database, username and password in the storage section.
I edited a config file but nothing changed.
Run /shardshop admin reload. Changes made in the admin menus apply right away without a reload.
Do I need DecentHolograms?
No. Version 2 builds stands from Minecraft's own display entities, and the plugin has no required dependencies.
#Updating
Manual update
Stop the server, replace the old jar in plugins/ with the new one and start it again. Your configs and data are kept. Missing config keys use the defaults, so your current config keeps working.
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.
updates:
enabled: true
check-on-startup: true
# Hours between checks, from 1 to 168.
check-interval-hours: 24
# Download new versions by themselves. They install on the next restart, and the old jar is kept in plugins/mcShardShop/backup.
auto-download: false
# Tell the console and admins (mcshardshop.admin) about updates.
notify: true
# Leave these blank to use the built-in values.
shared-token: ""
resource-id: 0
- The check runs shortly after startup (when
check-on-startupis on) and then everycheck-interval-hourshours (1 to 168). It never runs on the main thread. - With
notify: true, the console and players withmcshardshop.adminare told when a newer version exists. Admins also see the notice a few seconds after they join. - With
auto-download: true, the plugin downloads the new jar, checks that it is mcShardShop at the expected version, copies your current jar toplugins/mcShardShop/backupand places the new one in the server's update folder. It installs on the next restart. The jar that is running 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/mcShardShop/backup. Put it back in plugins/ to return to the old version.