ShopShelves Spigot Plugin - Container-Linked & Player-Owned Shops

ShopShelves is available as a Spigot/Paper/Velocity plugin, adapting the popular Fabric mod's functionality to the server-side platform, utilizing Vault for economy integration. This plugin transforms the Shelf Block (available in Minecraft 1.21.9+) into fully functional shops for Spigot-based servers.

Dependencies

Required Plugin: Vault

• Vault is required to enable all economy features (buying and selling).
• If Vault is not found, economy features will be disabled for non-operators.

Features

Robust Shop Types

• Admin Shops (Buy/Sell/Dual): Admins can set up persistent shops using the Shelf Block for buying, selling, or dual trade.
• Player Shops (PlayerShelves): Players can create their own shops by Sneaking + Placing a Shelf Block against a chest or barrel.
  • Automatically links to the container (including double chests) for stock.
  • Supports custom prices set per player using the item stamping command (/shops price...).
  • Single Item Restriction: Configurable option to restrict PlayerShelves to holding only one item type at a time to prevent confusion and ensure clear pricing.
  • Limits player shop creation based on permission nodes and a configurable default limit.

Dynamic Item Pricing & Stamping

• Global Configuration (pricing.yml): Set default buy and sell prices for items. The system recognizes data-rich items like potions, enchanted books, ominous bottles, suspicious stew, and goat horns to assign specific prices.
• Custom Price Stamps: Use the /shops price command to apply a one-time price stamp to a held item. This stamped item is then used to configure PlayerShelves with custom pricing or to set custom slot prices on Admin Shops.
• Flexible Pricing Ratios: Define prices based on quantity (e.g., $10 for 64 dirt) using the amount argument, allowing the shop to calculate the correct unit price for trade.
• Transaction Handling: Utilizes the Vault API for secure withdrawals and deposits, with transaction success/failure logged via server logs.

Advanced Text Display & Aesthetics

• Dynamic Floating Text: Shop price and mode information is displayed using Minecraft Text Display Entities. The displays automatically update when stock changes, the price is modified, or the shop goes "Out of Order" (container missing).
• Customizable Scaling: Configure the scale (size) of the main mode display, amount display, and price display independently (values 1-10).
• Range Control: Independently set the render distance (in blocks) for the main shop displays and the price displays.
• Two Price Display Modes:
  • TRIPLEPRICE: Shows the calculated price for the entire stack per slot.
  • SINGLEPRICE: Shows the unit price for the shelf, centered and merged if all items are the same type.
• Rich Text Formatting: All display text and chat messages support legacy color codes (&c) and hex color codes (&#RRGGBB).

Shop Management & Protection

• Player Shop Limits: Restrict the number of PlayerShelves a player can create using permission nodes (e.g., shopshelves.playershelves.10 for a limit of 10). The configurable default limit is 2.
• Admin Mode: Players with shopshelves.admin permission can enter a special "Admin Mode" using /shops admin to bypass all shop protections and quickly set up Admin Shops.
• Container Protection: Linked containers (chests/barrels) are protected from unauthorized access when linked to an active PlayerShelf.
• Explosion Protection: ShopShelves and their linked containers are protected from explosions.
• Hopper Protection: Items cannot be moved into or out of a ShopShelf inventory via hoppers or similar mechanics.
• Config Reload: Use /shops reload to refresh all settings, prices, and messages without a server restart.
• Full Update: Use /shops update to re-render all floating text displays across all loaded chunks/worlds.

Commands

• /shops, /shopshelves (Displays the main help page with clickable commands).
• /shops admin (Toggles admin mode to bypass shop protection and easily configure shops).
• /shops reload (Reloads config.yml, pricing.yml, and messages.yml).
• /shops update (Forces a re-render of all floating text displays).
• /shops mode [mode_name] (Views or sets the Message Delivery Mode or Price Display Mode).

Global Pricing Commands (Requires shopshelves.itemprice):

• /shops itemprice (Shows the current global price settings for the held item).
• /shops itemprice <price> <type> [amount] (Sets the global price for the held item in pricing.yml).
  • <type>: buy, sell, or both.
  • [amount]: The quantity the price applies to (e.g., 64).

Custom Price Stamp Command (Requires shopshelves.price):

• /shops price <price> <type> [amount] (Creates or modifies a one-time price stamp on the held item).
  • Note: Only one item with a price stamp is allowed in a player's inventory at a time.

Permissions

API Integration Guide: The ShopshelvesApi

For plugin developers, ShopShelves offers a safe API to check for shop entities.

package me.andy.shopShelvesSpigot.api;

import me.andy.shopShelvesSpigot.logic.ShopHelper; import org.bukkit.block.BlockState; import org.bukkit.block.Shelf; import org.jetbrains.annotations.Nullable;

import java.util.Optional; import java.util.UUID;

/**

• Public API for the ShopShelves Spigot plugin.

• Other plugins should use this class to safely check and interact with ShopShelves entities. */ public final class ShopshelvesApi {

  private static final ShopshelvesApi INSTANCE = new ShopshelvesApi();

  // Private constructor to prevent external instantiation private ShopshelvesApi() {}

  /**

  • Retrieves the singleton instance of the ShopShelves API.
  • @return The API instance. */ public static ShopshelvesApi getInstance() { return INSTANCE; }

  /**

  • Checks if a given BlockState is an active ShopShelf (any mode other than NONE).
  • This is the preferred way for other plugins to detect a shop.
  • @param blockState The BlockState to check.
  • @return True if it is a Shelf BlockState with an active mode. */ public boolean isShopShelf(@Nullable BlockState blockState) { if (!(blockState instanceof Shelf) || !ShopHelper.isShelf(blockState.getType())) { return false; } // Only return true if the shop mode is explicitly set to something other than NONE return ShopHelper.getShopMode(blockState) != ShopHelper.ShopMode.NONE; }

  /**

  • Gets the current shop mode for a BlockState, if it is an active ShopShelf.
  • @param blockState The BlockState to check.
  • @return The ShopHelper.ShopMode if it is a shop, otherwise Optional.empty(). */ public Optional<ShopHelper.ShopMode> getShopMode(@Nullable BlockState blockState) { if (blockState != null && isShopShelf(blockState)) { return Optional.of(ShopHelper.getShopMode(blockState)); } return Optional.empty(); }

  /**

  • Gets the UUID of the owner of the shop, if it is an active ShopShelf.
  • @param blockState The BlockState to check.
  • @return The owner's UUID if available, otherwise Optional.empty(). */ public Optional<UUID> getShopOwner(@Nullable BlockState blockState) { if (blockState != null && isShopShelf(blockState)) { return ShopHelper.getOwner(blockState); } return Optional.empty(); } }

💬 Primary Support Channel (Preferred)

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 one of my mods/plugins.
• Requirement: You must be the owner of the server.
• Time Zone: I am operating in the (CET/CEST) Time Zone.
• PM Hours: Please only send private messages between 10:00 AM and 10:00 PM (Brussels Time).

I will endeavor to answer your PM as soon as I can to be helpful and see what I can do to resolve your urgent issue. However, please understand that immediate responses are not guaranteed, and private messaging is a professional courtesy, not an entitlement. Thank you for your understanding and cooperation!

For mod developers, ShopShelves offers the shop shelfblock functions via the ShopshelvesApi class.

package me.andy.shopshelves.api;

import me.andy.shopshelves.logic.ShopHelper; import me.andy.shopshelves.util.ShopShelf; import net.minecraft.block.entity.BlockEntity; import net.minecraft.block.entity.ShelfBlockEntity; import org.jetbrains.annotations.Nullable;

import java.util.Optional; import java.util.UUID;

/**

• Public API for the ShopShelves mod.

• Other mods should use this class to safely check and interact with ShopShelves entities. */ public final class ShopshelvesApi {

  private static final ShopshelvesApi INSTANCE = new ShopshelvesApi();

  // Private constructor to prevent external instantiation private ShopshelvesApi() {}

  /**

  • Retrieves the singleton instance of the ShopShelves API.
  • External mods should call Shopshelves.api() to get this instance.
  • @return The API instance. */ public static ShopshelvesApi getInstance() { return INSTANCE; }

  /**

  • Checks if a given BlockEntity is an active ShopShelf (any mode other than NONE).
  • This is the preferred way for other mods to detect a shop.
  • @param blockEntity The BlockEntity to check.
  • @return True if it is a ShelfBlockEntity implementing ShopShelf with an active mode. */ public boolean isShopShelf(@Nullable BlockEntity blockEntity) { if (!(blockEntity instanceof ShelfBlockEntity) || !(blockEntity instanceof ShopShelf shopShelf)) { return false; } // Only return true if the shop mode is explicitly set to something other than NONE return shopShelf.getShopMode() != ShopHelper.ShopMode.NONE; }

  /**

  • Gets the current shop mode for a BlockEntity, if it is an active ShopShelf.
  • @param blockEntity The BlockEntity to check.
  • @return The ShopHelper.ShopMode if it is a shop, otherwise Optional.empty(). */ public Optional<ShopHelper.ShopMode> getShopMode(@Nullable BlockEntity blockEntity) { if (blockEntity instanceof ShopShelf shopShelf && isShopShelf(blockEntity)) { return Optional.of(shopShelf.getShopMode()); } return Optional.empty(); }

  /**

  • Gets the UUID of the owner of the shop, if it is an active ShopShelf.
  • @param blockEntity The BlockEntity to check.
  • @return The owner's UUID if available, otherwise Optional.empty(). */ public Optional<UUID> getShopOwner(@Nullable BlockEntity blockEntity) { if (blockEntity instanceof ShopShelf shopShelf && isShopShelf(blockEntity)) { return shopShelf.getOwner(); } return Optional.empty(); } }

• shopshelves.command: Allows access to the base /shops help command. (Default for all players)
• shopshelves.admin: Allows usage of /shops admin mode. (Requires OP Level 2)
• shopshelves.reload: Allows usage of /shops reload. (Requires OP Level 2)
• shopshelves.update: Allows usage of /shops update. (Requires OP Level 4)
• shopshelves.mode: Allows usage of /shops mode for configuring display/message settings. (Requires OP Level 4)
• shopshelves.itemprice: Allows usage of /shops itemprice to manage global pricing. (Requires OP Level 2)
• shopshelves.price: Allows usage of /shops price to create custom price stamps. (Requires OP Level 2)
• shopshelves.playershelf: Allows a player to create PlayerShelves. (Requires OP Level 2)
• shopshelves.playershelves.unlimited: Grants unlimited PlayerShelf creation. (Requires OP Level 4)
• shopshelves.playershelves.<number>: Sets the maximum number of PlayerShelves a player can create (e.g., .10 for a limit of 10). (Requires OP Level 2)