ShopShelves

ShopShelves – Admin Shops & Player-Owned Shops

Using Bukkit, Spigot, Paper or Purpur?
The plugin version can be found on the SpigotMC page.

ShopShelves turns the Shelf Block into interactive, server-friendly display shops! Admins create permanent fixed-price shops, and players set up their own chest-linked Player Shelves with custom prices, all powered by the EcoBal economy. Prices, stock and shop status are shown live with lag-friendly Text Displays.

Want item-for-item trades too? Check out TradeShelves, built on the same interaction and protection system and fully compatible with ShopShelves. Then make shopping even better with the WIITS client side mod!

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.)

Required Mod: EcoBal Economy API

✨ Features & Highlights

Native Shop Block

• Uses the Shelf Block as the shop itself: no signs, no armor stands, just a clean, immersive look.

Dual Shop Modes

• Admin Shops (Buy / Sell / Dual): Permanent shops with infinite stock for buying, selling, or both. Admin shops are never restricted by the world allowlist.
• Player Shops (Player Shelves): Players create their own shop by sneaking + placing a Shelf Block against a chest, barrel or copper chest.
• Automatically links to the container, including double chests, for stock management.
• Custom prices per slot via the in-game Price GUI.
• Optional single-type mode (limit_playershelf_to_single_type): one item type across all three slots with a shared price, or a different item and price per slot.
• Shows Out of Order when the linked container is missing.
• When the linked container is broken, the shelf resets to a plain vanilla shelf, with no leftover floating text or stale data.

Price GUI

• Owners shift + right-click their shelf to open a full price management GUI: use +/− buttons to adjust buy/sell prices per slot, or type an exact value (and amount) in chat. No commands required.
• Reset any slot back to the global config prices with one click.

Custom Shop Labels

• Set a personalized floating label from the Price GUI with the name tag button: left-click to type it in chat, right-click to remove it.
• Supports color codes (&c, &l, …), hex colors (&#RRGGBB) and a second line (\n or &n). Color support can be granted per permission.
• label_max_length counts only visible characters. Brackets and colors are configurable separately for admin and player shops, with a brackets_per_line toggle.

Shop Viewer & Statistics

• Customers shift + click the top edge of a shelf to open a read-only viewer with the full items (potions, enchantments, etc.).
• The Statistics Book shows the total money earned and lost per slot. It is stored on the shelf, so it survives restarts.

Flexible Pricing System

• Global Prices: Set default prices for any item in pricing.yml or with /shops itemprice, including potions, enchanted books, goat horns, player heads and more.
• Custom Price Stamps: Use /shops price to stamp a one-off price onto a held item, then put it on a shelf.
• Per-Slot Control: Each slot can have its own buy price, sell price and stack amount (e.g. $10 for 64 dirt).

Lag-Friendly Text Displays

• Prices, stock and status are shown with Minecraft’s Text Display Entities: no packet hacks, no legacy holograms. They only rebuild when something actually changes and re-sync to clients less often.
• Configurable Scaling: Size the header, amount and price displays independently (1–10).
• View Range: Separate render distances for shop headers and price tags.
• Two Price Display Modes: TRIPLEPRICE (a price per slot) or SINGLEPRICE (one merged price).
• Item Language: Localize item names with any Minecraft locale (en_us, de_de, fr_fr, …).

Protection & Security

• Linked containers can only be opened or broken by their owner or an admin.
• Shop shelves and their linked containers are immune to explosions and the wither, and hoppers can’t take items out of or put items into active shops.
• The front-face item slots can’t be broken by accident: owners and admins break a shelf by hitting its top or bottom edge.

Shop Management

• Player Shop Limits: Cap player shelves per player with permissions (e.g. shopshelves.playershelves.5) or grant unlimited.
• World Allowlist: Restrict player shops to specific worlds with allowed_worlds. Admins can grant per-world or blanket bypass permissions.
• Admin Mode: /shops admin lets operators bypass all protections and set up shops.
• Chop Stick: /shops chopstick gives a stick that refreshes a shop display (right-click) or cycles an admin shop’s mode (sneak + right-click).
• Config Auto-Migration: New config.yml and messages.yml keys are added automatically on updates.

Made to work with TradeShelves

Install TradeShelves next to ShopShelves and they detect each other on startup and work together:

• One shelf, two hands: Player shops made with the main hand become ShopShelves shops and player shops made with the off-hand become trade shelves (swap it with TradeShelves_offhand). Admin shops keep using each mod’s own admin mode.
• Money and trades on one chest: An owner can put a ShopShelves shop and a trade shelf on the same chest. Other players can’t use a chest that is already linked to someone else’s shop.
• One reload: /shops reload or /trades reload reloads both mods, ShopShelves first.
• Shared permissions and limits: Optionally let TradeShelves use the ShopShelves permission nodes and player shop limit (see Compatible Settings below).
• ShopShelves always takes priority, and both mods leave each other’s shelves alone.

⚙️ Setup & Usage

1. Admin Shop Setup

1. Place a Shelf Block.
2. Enter Admin Mode: run /shops admin.
3. Set Mode: while sneaking, right-click the middle of the shelf to cycle NONE → BUY → SELL → DUAL.
4. Set Item & Price: hold an item (with a global price configured, or with a Price Stamp) and right-click a slot to fill it.
5. Price GUI: sneak + right-click the top or bottom edge of the shelf.

2. Player Shop Setup

1. Place a Chest, Barrel or Copper Chest.
2. Link Shelf: while sneaking, place a Shelf Block against the container. The shelf is linked automatically. With TradeShelves installed, use your main hand (or the off-hand if the server swapped it).
3. Set Price: shift + right-click your shelf to open the Price GUI.
4. Stock Your Shop: add items to the linked container. The display updates automatically.

3. Customer Interactions

• Right-click slot: buy one stack.
• Left-click slot: sell one stack.
• Sneak + click (admin shops): buy or sell a full stack at once.
• Shift + click top edge: open the read-only shop viewer.

Commands

• /shops, /shopshelves: Opens the help menu with clickable commands.
• /shops admin [player]: Toggles admin setup mode for yourself or another player.
• /shops reload: Reloads config.yml, pricing.yml and messages.yml and refreshes displays. Also reloads TradeShelves when installed.
• /shops update: Forces a full refresh of all shop text displays.
• /shops mode [mode]: Views or sets the message delivery mode (CHAT | ACTIONBAR | BOTH) or price display mode (SINGLEPRICE | TRIPLEPRICE).
• /shops itemprice [price] [buy|sell|both] [amount]: Views or sets the global price for the held item.
• /shops price <price> [buy|sell|both] [amount]: Stamps a custom one-off price onto the held item. Only one stamped item is allowed in your inventory at a time.
• /shops chopstick: Gives you the Chop Stick.

Permissions

Compatible Settings

These settings in the ShopShelves config.yml only do something when TradeShelves is installed too. ShopShelves takes priority, so it owns them.

# ─── Compatible settings (only used when TradeShelves is installed) ───
# true:  ShopShelves player shops use the main hand, TradeShelves player shops use the off-hand.
# false: the other way around.
TradeShelves_offhand: true
# true: TradeShelves uses the ShopShelves permission nodes (tradeshelves.X = shopshelves.X).
TradeShelves_permissions: false
# true: TradeShelves uses the default player shop limit from this config.
TradeShelves_ownlimit: false

Shared permissions: With TradeShelves_permissions: true, every tradeshelves.X node is checked as shopshelves.X (for example shopshelves.playershelf, shopshelves.playershelves.5), and tradeshelves.arrow becomes shopshelves.mode.

ShopshelvesApi api = ShopshelvesApi.getInstance();

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

// Shop mode: BUY, SELL, DUAL or PLAYERSHELF
Optional<ShopHelper.ShopMode> mode = api.getShopMode(blockEntity);

// Owner UUID of a player-owned shelf
Optional<UUID> owner = api.getShopOwner(blockEntity);

public interface MyShelf {
    // ShopShelves / TradeShelves ignore every shelf where this returns true
    default boolean isShelfClaimed() {
        return isMyShelfActive();
    }

    boolean isMyShelfActive();
}

Requirements

• Minecraft: 26.3
• Loader: Fabric Loader + Fabric API (server-side only, no client install needed)
• Required: EcoBal (economy)
• Optional: LuckPerms + Fabric Permissions API for permission nodes
• Optional: TradeShelves: item-for-item trades next to your shops, with the compatible settings above

Modpack Policy

• You ARE PERMITTED to include ShopShelves in any modpack.
• Credit is appreciated but not strictly required.
• Please do not modify the mod’s JAR file directly.
• The modpack itself, or access to this mod within the modpack, must not be sold.