ShopShelves | Player & Admin shops icon

ShopShelves | Player & Admin shops -----

New advanced way of admin shops and playershops. ShopShelves and PlayerShelves



ShopShelves Spigot: The Modern Display Shop Solution

The ultimate plugin for creating interactive, visually striking display shops using the Shelf Block. Transform your server's economy with elegant, lag-friendly holograms (Text Displays) that show prices, stock, and shop status in real-time!


Pictures explained:
The following pictures depict the in-game shelf blocks in order:

Buy Shop | Sell Shop | Buy & Sell Shop | Custom Label | Player Shop

Statistics Book → Shows the total money earned / lost per item slot.

Custom Price GUI — Shift right-click your shelf to set custom prices per slot.

Customer-friendly viewer GUI to inspect the full item (potions, enchantments, etc.)



[​IMG] [​IMG] [​IMG] [​IMG] [​IMG] [​IMG] [​IMG] [​IMG]

Also check out my DrawerShelves plugin here!

Primary Support Channel (Preferred)
Discord Server: https://discord.gg/48sZCbdHzJ

All general questions, feature requests, and non-urgent bug reports should be posted in the appropriate channels on our Discord server. We actively monitor the server and will respond as soon as possible. This ensures that the whole community can benefit from the discussion and solutions.


---

Urgent Private Messaging (PM) Policy
While we prefer all issues to be handled via the Discord server first, you are welcome to PM me directly under specific urgent circumstances:
  • Allowed Reason: Your server is crashing or experiencing critical, game-breaking errors directly related to this plugin.
  • Requirement: You must be the owner of the server.
  • Time Zone: I operate in the Belgium / Brussels Time Zone (CET/CEST).
  • PM Hours: Please only send private messages between 10:00 AM and 10:00 PM (Brussels Time).
I will do my best to respond promptly, but immediate replies are not guaranteed. Private messaging is a professional courtesy, not an entitlement. Thank you for your understanding!

— — — — — — — — — — — — — — — — — — — — — — —​

✨ Features & Highlights

  • Native Shop Block: Uses the Shelf Block as the dedicated shop block — no signs, no armor stands, just a clean immersive look.
  • Lag-Friendly Text Displays: Prices and status are shown using Minecraft's modern Text Display Entities — no packet hacks, no legacy holograms.
    • Configurable Scaling: Adjust the size of the main label, amount, and price displays independently via config.
    • Dynamic View Range: Set separate render distances for shop headers and price tags to optimize client FPS.


  • Dual Shop Modes: Supports Admin Shops (infinite stock) and Player Shops (linked to containers).
  • Price GUI: Owners Shift-Click their shelf to open a full price management GUI — use +/− buttons to adjust buy/sell prices per slot, or type a value directly in chat. No commands required.
  • Custom Shop Labels: Set a personalized display name for your shop directly from the Price GUI using the name tag button. Color code support can be granted per-permission.
  • Shop Viewer: Non-owners can Shift-Click the top edge of a shelf to open a read-only info panel showing stock, prices, and shop details.
  • Flexible Pricing System:
    • Global Prices: Set default prices for any item type via pricing.yml or the /shops itemprice command.
    • Custom Price Stamps: Use /shops price to stamp a one-off price onto an item and apply it to a specific shelf slot.
    • Per-Slot Control: Each slot on a shelf can have its own independent buy/sell price and stack amount.


  • Sales & Taxes: Run server-wide or per-player economic events using the built-in deal system.
    • Apply a global sale or tax instantly — all admin shop text displays update automatically.
    • Target individual players with personal discounts or surcharges.
    • Set a timed duration (e.g. 30m, 12h, 7d) or make it permanent.
    • Stacking logic: players can hold multiple deals simultaneously — the highest sale and the highest tax each win their respective side, then they cancel each other out.
    • Player shops are immune — deals are an admin tool and never affect player-owned shelf shops.
    • Optional online-only countdown mode: personal deal timers only tick down while the player is connected.


  • Single-Type Mode: Optionally restrict Player Shelves to a single item type across all slots — prevents confusion and keeps shops tidy.
  • World Allowlist: Restrict player shops to specific worlds using the /shops worlds command or config. Admins can grant per-world or blanket bypass permissions.
  • WorldGuard Support: Respects the allow-shop WorldGuard flag — block player shop creation in protected regions with a single flag.
  • Player Shop Limits: Cap the number of player shelves per player using permission-based limits (e.g. shopshelves.playershelves.5) or grant unlimited via a single node.
  • Protection & Security: Linked containers are protected from unauthorized access and grief. Explosions, fire, pistons, and hoppers cannot destroy or bypass active shops.
  • Vault Economy Integration: Works with any Vault-compatible economy plugin out of the box.
  • Configurable Messages: Every player-facing message is defined in messages.yml with full color code, hex color, and action bar support.
  • Developer API: A clean public API lets other plugins detect shops, read ownership, and apply price modifiers programmatically. See the Developer API section below.

— — — — — — — — — — — — — — — — — — — — — — —​

⚙️ Setup & Usage

1. Admin Shop Setup
  • Place a Shelf Block.
  • Enter Admin Mode: Run /shops admin.
  • Set Mode: While sneaking, Right-Click the shelf to cycle through modes: NONE → BUY → SELL → DUAL.
  • Set Item & Price: Hold an item (with a global price configured, or with a Price Stamp applied) and Right-Click a slot to fill it.

2. Player Shop Setup
  • Place a Chest or Barrel.
  • Link Shelf: While sneaking, Right-Click the container with a Shelf item in hand. The shelf is placed and linked automatically.
  • Set Price: Shift-Click your shelf to open the Price GUI and adjust buy/sell prices.
  • Stock Your Shop: Add items to the linked container. The shelf display updates automatically.

3. Customer Interactions
  • Right-Click Slot: Buy one stack.
  • Left-Click Slot: Sell one stack.
  • Sneak + Click: Buy or sell a full stack at once.
  • Shift-Click top edge: Open the read-only shop viewer.

4. Sales & Taxes
  • /shops sale 20 — Global 20% sale on all admin shops (permanent).
  • /shops sale 20 12h — Global 20% sale for 12 hours.
  • /shops sale 20 12h PlayerName — Personal 20% sale for a specific player for 12 hours.
  • /shops tax 15 — Global 15% tax surcharge (permanent).
  • /shops sale clear — Remove the active global sale.
  • /shops tax clear PlayerName — Remove all active taxes for a player.
  • /shops deals — View active global and personal sale/tax percentages.
Duration tokens: 30m (minutes) · 6h (hours) · 7d (days)

— — — — — — — — — — — — — — — — — — — — — — —​

Commands & Permissions

Command Permission Description
/shops shopshelves.command Opens the help menu.
/shops admin shopshelves.admin Toggles Admin Setup Mode.
/shops reload shopshelves.reload Reloads all configs and refreshes displays.
/shops update shopshelves.update Forces a full refresh of all shop text displays.
/shops mode [mode] shopshelves.mode Views or sets the message delivery / price display mode.
/shops itemprice [price] [type] [amount] shopshelves.itemprice Views or sets the global price for the held item.
/shops price [price] [type] [amount] shopshelves.price Stamps a custom one-off price onto the held item.
/shops worlds shopshelves.worlds Lists the current player shop world allowlist.
/shops worlds add [world] shopshelves.worlds Adds a world to the player shop allowlist.
/shops worlds remove [world] shopshelves.worlds Removes a world from the player shop allowlist.
/shops sale [%] [duration] [player] shopshelves.sale Applies a sale discount globally or to a player.
/shops sale clear [player] shopshelves.sale Removes the active global sale, or clears a player's sales.
/shops tax [%] [duration] [player] shopshelves.tax Applies a tax surcharge globally or to a player.
/shops tax clear [player] shopshelves.tax Removes the active global tax, or clears a player's taxes.
/shops deals shopshelves.deals Displays active global and personal sale/tax percentages.
N/A shopshelves.sale.[N] Allows applying a sale up to N% (e.g. shopshelves.sale.20).
N/A shopshelves.sale.# Allows applying a sale of any percentage (unlimited).
N/A shopshelves.tax.[N] Allows applying a tax up to N% (e.g. shopshelves.tax.20).
N/A shopshelves.tax.# Allows applying a tax of any percentage (unlimited).
N/A shopshelves.playershelf Grants the ability to create player shelves.
N/A shopshelves.playershelves.[limit] Sets the max player shelves (e.g. .5, .10).
N/A shopshelves.playershelves.unlimited Grants unlimited player shelves.
N/A shopshelves.playershelf.worlds Bypasses the world allowlist for all worlds.
N/A shopshelves.playershelf.[worldname] Bypasses the world allowlist for a specific world.
N/A shopshelves.setlabel Allows setting a custom shop label via the price GUI.
N/A shopshelves.setlabel.color Allows color/formatting codes in custom shop labels.


— — — — — — — — — — — — — — — — — — — — — — —​

️ Deal Placeholders

These placeholders are available in messages.yml and can be used in any message or display format string. They reflect the combined active sale and tax for the viewer.

Placeholder Output Example
%sale% Net sale % after cancellation. 0 if no sale. 20
%tax% Net tax % after cancellation. 0 if no tax. 15
%sale_format% Always shows "Sale X%" even when 0. Sale 20%
%tax_format% Always shows "Tax X%" even when 0. Tax 15%
%if_sale% Shows "Sale X%" only when a sale is active, otherwise empty. Sale 20%
%if_tax% Shows "Tax X%" only when a tax is active, otherwise empty. Tax 15%
%global_deal% Shows the winning side for global deals only (sale or tax, after they offset each other). Sale 5%
%player_deal% Shows the winning side for the full combined result (global + personal). Uses whichever side is larger after cancellation. Sale 10%


Resolution logic: If a player has a 25% sale and a 20% tax active, %player_deal% shows Sale 5% — the net result after they cancel each other out. Global deals take priority over personal deals when the global percentage is higher on that side.

— — — — — — — — — — — — — — — — — — — — — — —​

Developer API

ShopShelves exposes a public API class at me.andy.shopShelvesSpigot.api.ShopshelvesApi that other plugins can use to interact with the plugin safely. Get the singleton instance and you have access to shop detection, ownership queries, and the full price modifier system.

Getting the instance
Code (Java):

ShopshelvesApi api = ShopshelvesApi. getInstance ( ) ;
 
Detecting a shop shelf
Code (Java):

// Check if a block is an active shop of any kind
boolean isShop = api. isShopShelf (block. getState ( ) ) ;

// Get the shop mode (BUY, SELL, DUAL, PLAYERSHELF)
Optional <ShopHelper. ShopMode > mode = api. getShopMode (block. getState ( ) ) ;

// Get the owner UUID of a player-owned shelf
Optional <UUID > owner = api. getShopOwner (block. getState ( ) ) ;
 
Applying a price modifier to a player

The modifier is a multiplier relative to the listed price:
  • 0.80 → player pays 80% (20% discount)
  • 1.00 → no change (clears any existing modifier)
  • 1.20 → player pays 120% (20% surcharge)

Code (Java):

// Permanent 20% discount
api. setPlayerPriceModifier (playerUuid, 0.80 ) ;

// Timed 15% surcharge for 1 hour
api. setPlayerPriceModifier (playerUuid, 1.15, 60 * 60 * 1000L ) ;

// Using a live Player reference
api. setPlayerPriceModifier (player, 0.90 ) ;
api. setPlayerPriceModifier (player, 0.90, 30 * 60 * 1000L ) ;
 
Reading back the effective multiplier
Code (Java):

// Returns the combined effective multiplier (API + command deals + global deals)
double multiplier = api. getEffectivePriceMultiplier (playerUuid ) ; // e.g. 0.80

// Check if any deal is currently active for a player
boolean hasModifier = api. hasActiveModifier (playerUuid ) ;
 
Removing a modifier
Code (Java):

// Removes any modifier your plugin previously set for this player
api. removePlayerPriceModifier (playerUuid ) ;
api. removePlayerPriceModifier (player ) ; // live Player overload
 
Important notes for developers
  • Modifiers set via the API only affect admin shops (BUY / SELL / DUAL). Player-owned shelf shops (PLAYERSHELF) are always immune.
  • Modifiers persist across restarts — they are stored in the plugin's SQLite database.
  • Multiple modifiers from multiple sources (API, /shops sale command, global deals) stack using the same resolution: highest sale wins, highest tax wins, they cancel each other out.
  • Calling setPlayerPriceModifier again replaces your plugin's previous modifier for that player — it does not add on top of it.
  • The multiplier must be greater than 0.0 and at most 10.0. An IllegalArgumentException is thrown for values outside this range.
  • Pass durationMs <= 0 for a permanent modifier.

Listening to shop events

ShopShelves fires three Bukkit events that you can listen to in your own plugin:

Code (Java):

// Fired before a player shop is created — cancellable
@EventHandler
public void onShopCreate (ShopShelfCreateEvent event ) {
    Player player   = event. getPlayer ( ) ;
    Location loc     = event. getLocation ( ) ;
    ShopMode mode   = event. getShopMode ( ) ;
    event. setCancelled ( true ) ; // prevent creation
}

// Fired before a shop is removed — cancellable
@EventHandler
public void onShopRemove (ShopShelfRemoveEvent event ) {
    ShopMode previous = event. getPreviousMode ( ) ;
}

// Fired before any buy or sell transaction — cancellable
@EventHandler
public void onTransaction (ShopTransactionEvent event ) {
    Player buyer   = event. getPlayer ( ) ;
    UUID   owner   = event. getShopOwnerUuid ( ) ; // null for admin shops
    double price   = event. getPrice ( ) ;
    int    amount = event. getAmount ( ) ;
    ShopTransactionEvent. TransactionType type = event. getTransactionType ( ) ; // BUY or SELL
    event. setCancelled ( true ) ; // cancel the transaction
}
 
All events are in the package me.andy.shopShelvesSpigot.event.

— — — — — — — — — — — — — — — — — — — — — — —​

Requirements
  • Minecraft: 1.21.9 – 1.21.11
  • Server: Spigot or Paper
  • Required: Vault + a compatible economy plugin (e.g. EssentialsX Economy)
  • Optional: WorldGuard — enables the allow-shop region flag
Resource Information
Author:
----------
Total Downloads: 442
First Release: Nov 17, 2025
Last Update: Apr 27, 2026
Category: ---------------
All-Time Rating:
7 ratings
Find more info at modrinth.com...
Version -----
Released: --------------------
Downloads: ------
Version Rating:
----------------------
-- ratings