All documentation
Documentation

mcShardShop

A rotating shop where items float on stands in your world, change on a schedule and sell out for real, with its own currency and a full in-game editor.

v2.0.1 Paper 1.21.4 or newer (including 26.1) or a Paper forkJava 21 or newerOptional: Vault, PlayerPoints, PlaceholderAPI

Quick start

  1. Drop mcShardShop-2.0.1.jar into plugins/ and restart the server. No other plugin is needed.
  2. Stand where an item should float and run /shardshop admin stand create. Repeat for every stand. The number of stands is the number of items on sale.
  3. Stand where players should arrive and run /shardshop admin setwarp. Players then use /shardshop to get there.
  4. Run /shardshop admin setboard to place the info board with the live countdown.
  5. Replace the 18 starter items. Run /shardshop admin to open the editor, or hold an item and run /shardshop admin additem 500 rare.
  6. Click a stand to try a purchase. Run /shardshop admin rotate to rotate the shop on the spot.

#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

  1. Put the jar in your server's plugins/ folder.
  2. Restart the server. The plugin creates plugins/mcShardShop/ with config.yml, items.yml, earning.yml, messages.yml, menus.yml, holograms.yml and webhooks.yml.
  3. The console prints a line such as Ready: 18 items, 0 stands, rotation #1. when startup is done.
Works out of the box

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.

Database errors

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 list lists 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.

Sending players with NPCs

/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 permission the player lacks.
  • The purchase cooldown has not passed (bypass: mcshardshop.bypass.cooldown).
  • The inventory is full and purchase.full-inventory is block.

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 admin opens 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 in config.yml (Common by default). Prices accept 5k, 2.5k, 1m and 1b.

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: true keeps an item on sale in every rotation.
  • season: {from: "12-01", to: "12-31"} limits an item to a date range (month-day).
  • enabled: false hides it without deleting it. deals: false keeps it out of random discounts.

Stock and limits

  • stock is shared by every player and resets each rotation. -1 is unlimited.
  • limit is per player each rotation. lifetime-limit is 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 example end_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: interval rotates every every (for example 12h, 3d, 1d12h). mode: daily rotates each day at time. mode: weekly rotates on day at time. time uses a 24-hour clock.
  • Set enabled: false to rotate only by hand. An interval of 0 is also an off switch.
  • timezone takes names such as America/New_York. Blank uses the server clock.
  • avoid-repeats keeps an item out of the shop for that many rotations, when there are enough other items.
  • warnings are 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|set and payments all go through that plugin.
  • The leaderboard (/shards top) and starting-balance and max-balance only 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.

Pay shards from other plugins

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.

Operators do not get multipliers automatically

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.

#The admin menu

/shardshop admin opens a menu with these buttons:

  • Items: add, edit and remove catalog items, with pages for long lists.
  • Rotation: see what is on sale, swap items or rotate now.
  • Stands: place, move and remove stands.
  • Settings: schedule, deals, currency and stand effects, with no reload needed.
  • Shop Warp: set the warp to your position.
  • Reload: reload every config file.

Reports

  • /shardshop admin stats [days] shows items sold, total revenue and your best sellers for the last N days (default 7).
  • /shardshop admin history <player> shows a player's 10 latest purchases.

#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 &#RRGGBB and MiniMessage such as <gradient:#FF55FF:#55FFFF> work in every text field.
  • Keys you delete from messages.yml fall back to the built-in text.
  • The messages section of config.yml turns titles, action bar messages, sounds and the join notice on or off. The sounds section 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:

  • ShardPurchaseEvent fires before a purchase is charged. It can be cancelled, and its price can be changed.
  • ShardRotationEvent fires 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.

CommandWhat it doesPermission
/shardshopWarp to the shop.mcshardshop.warp
/shardshop catalogBrowse every item the shop can sell and manage your wishlist. Also works as /shardshop wishlist.mcshardshop.catalog
/shardshop claimCollect items that did not fit in your inventory.none
/shardshop historyYour purchases.none
/shardshop helpShow the player help.none
/shardsShow 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 topOpen the richest players leaderboard (built-in currency only).mcshardshop.shards.top
/shards dailyClaim 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 adminOpen 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 listList 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 rotateRotate the shop now.mcshardshop.admin
/shardshop admin setwarpSet the shop warp to your position.mcshardshop.admin
/shardshop admin setboardPlace the info board above your position.mcshardshop.admin
/shardshop admin removeboardRemove 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 reloadReload 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.

PermissionWhat it allowsDefault
mcshardshop.useBuy from stands.everyone
mcshardshop.warpUse /shardshop to go to the shop.everyone
mcshardshop.catalogBrowse the catalog and use the wishlist.everyone
mcshardshop.shards.balanceCheck your own balance.everyone
mcshardshop.shards.balance.othersCheck the balance of other players.op
mcshardshop.shards.payPay other players.everyone
mcshardshop.shards.topView the leaderboard.everyone
mcshardshop.shards.dailyClaim the daily reward.everyone
mcshardshop.shards.withdrawTurn 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.limitIgnore per-player purchase limits.nobody
mcshardshop.bypass.cooldownIgnore the cooldown between purchases.nobody
mcshardshop.adminAll 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.

PlaceholderValue
%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

SettingDefaultWhat it does
updates.enabledtrueTurn the BuiltByBit update check on or off.
updates.check-on-startuptrueCheck shortly after the server starts.
updates.check-interval-hours24Hours between checks, from 1 to 168.
updates.auto-downloadfalseDownload new versions by themselves. They install on the next restart.
updates.notifytrueTell the console and admins about updates.
updates.shared-token / resource-id"" / 0Leave blank to use the built-in values.
gui.live-update-seconds1How often open menus redraw their timers.
storage.typeSQLITESQLITE or MYSQL. See the mysql block for host, port, database, username, password, use-ssl and table-prefix.
storage.auto-save-minutes5Minutes between automatic saves.
currency.providerSHARDSSHARDS, VAULT or PLAYERPOINTS.
currency.singular / pluralShard / ShardsCurrency names.
currency.display-format&d%amount% %currency%How amounts look everywhere. Placeholders: %amount% %currency%.
currency.starting-balance100What new players start with (built-in currency).
currency.max-balance-1Highest balance. -1 for no maximum.
currency.pay.enabled / min-amount / tax-percenttrue / 1 / 0Player payments, the smallest payment, and the percent taken from each payment.
currency.vouchers.enabled / min-amounttrue / 10Allow /shards withdraw and set the smallest voucher.
rotation.enabledtrueWhen false, the shop only changes with /shardshop admin rotate.
rotation.modeintervalinterval, daily or weekly.
rotation.every7dInterval mode length, for example 12h, 3d, 1d12h.
rotation.time / day"18:00" / FRIDAYTime (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-repeats1Rotations an item stays out of the shop, when there are enough other items.
rotation.announcetrueChat message, title and sound when the shop changes.
rotation.warnings[24h, 1h, 10m, 1m]Warnings before a rotation.
deals.enabled / per-rotationtrue / 1Random discounts, and how many items get one each rotation.
deals.min-percent / max-percent10 / 30Range of the random discount.
rarities.<id>4 defaultsname, color, weight, guaranteed, glow, particle, base and announce for each rarity.
purchase.require-confirmationtrueShow the quantity and price screen before buying.
purchase.max-quantity64The most a player can buy in one go.
purchase.cooldown-seconds2Seconds between purchases. 0 for none.
purchase.full-inventoryclaimclaim, drop or block.
purchase.announce-rare / announce-sold-outtrue / trueTell the server about announce rarities being bought and about sold-out items.
messages.enable-titles / enable-actionbar / enable-sounds / join-noticetrueTurn feedback types on or off.
sounds.<key>see fileSound keys for menu-open, click, purchase, fail, rotation, warning, reveal, wishlist and earn. Blank for silence.
stands.*see fileitem-height, text-height, item-scale, text-width, text-range, base, spin, spin-degrees-per-second, bob, glow, particles, reveal.
board.scale / width / background-alpha1.5 / 300 / 96Info board size and background.
shop-warp.*emptyWarp 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-startup is on) and then every check-interval-hours hours (1 to 168). It never runs on the main thread.
  • With notify: true, the console and players with mcshardshop.admin are 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 to plugins/mcShardShop/backup and 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.
Rolling back

If auto-download was on, the previous jar is in plugins/mcShardShop/backup. Put it back in plugins/ to return to the old version.