ShopShelves

ShopShelves - Admin Shops & Player-Owned Shops

Using Bukkit, Spigot, Paper, or Purpur?
To get the most accurate list of features and general information for server plugins, please visit the Spigot site:
👉 View the Plugin version on the SpigotMC page

---

Recommended Client-Side Companion

Looking to enhance the shopping visual experience?
👉 WIITS - Client-side Shopping Mod

---

ShopShelves transforms the Shelf Block into flexible, server-friendly shops! This powerful server-side Fabric mod allows administrators to create permanent, fixed-price shops and gives players the ability to set up their own chest-linked "Player Shelves" with custom prices, all powered by a configurable in-game economy.

---

📷 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 total money earned / lost per slot item.
• Custom Price GUI → Shift right-click a shelf to set custom prices per slot.
• Customer-Friendly Viewer GUI → Inspect full item details (potions, enchantments, NBT data, etc.).

---

📦 Required Dependencies

Required Mod: EcoBal Economy API

---

✨ Features

Robust Shop Types

• Admin Shops (Buy / Sell / Dual): Admins can create persistent shops using the Shelf Block for buying, selling, or dual trade. Admin shops are immune to world allowlists and cannot be broken through the front-facing item slots.
• Player Shops (PlayerShelves): Players can create their own shops by Sneaking + Placing a Shelf Block against a chest, barrel, or copper chest.
  • Automatically links to the container (including double chests) for stock management.
  • Supports custom prices set per slot via the in-game Price GUI (shift right-click the shelf).
  • Configurable single-type mode: lock a player shop to one item across all three slots with a shared price, or allow each slot to hold different items.
  • Configurable creation limits via permission nodes.
  • Breaking the linked container automatically safely resets the shelf back to a plain vanilla shelf without leftover floating displays.

Custom Shop Labels

• Set a custom floating label on any shelf via the Price GUI.
• Supports legacy color codes (&c, &l, etc.), hex colors (&#RRGGBB), and newline markers (\n or &n).
• Surrounding whitespace around newlines is stripped cleanly.
• Length limit (label_max_length in config.yml, default 64) measures visible characters only.
• Fully configurable bracket formatting in messages.yml (toggle per-line or full-block brackets).
• Right-click the label icon in the Price GUI to clear the label instantly.

Dynamic Item Pricing

• Global Pricing (pricing.yml): Set default buy/sell values for items—including potions, enchanted books, goat horns, and player heads.
• Custom Price Stamps: Use /shops price to stamp held items with custom pricing rules to configure shelves on the fly.
• Flexible Quantity Ratios: Set prices by quantity (e.g., $10 for 64 blocks); unit values are calculated automatically.
• In-GUI Price Editing: Shift right-click any shelf to edit pricing via increment buttons or exact chat input.
• Instant Price Reset: Reset slot pricing to default values directly inside the GUI.

Statistics Book

• Track cumulative profits and losses per slot for both Admin Shops and Player Shelves.
• All profit/loss metrics persist across server reboots.

Display Aesthetics & Tech

• Dynamic Floating Text: Rendered using vanilla Text Display Entities that sync live with stock and price updates.
• Scale & Distance Tuning: Fully configurable render distances and text scaling multipliers (1–10).
• Two Display Modes: TRIPLEPRICE (individual price per slot) and SINGLEPRICE (merged price display).
• Localization: Supports standard Minecraft locale files (en_us, de_de, fr_fr, etc.) fetched on boot.

Server Protection & Management

• Break Protection: Shelf item slots (8×16 px hitboxes) ignore normal hit interactions; breaking requires targeting the border bands.
• Container Security: Linked storage cannot be opened or broken by unauthorized players.
• Explosion Proofing: Shelves and linked inventories resist TNT, creeper, and wither damage.
• Auto-Migration: Automatically updates configuration files with newly introduced keys without overwriting existing settings.
• Live Reloading: Refresh configurations on the fly via /shops reload.

---

💻 Commands

Command	Permission	Description
/shops or /shopshelves	shopshelves.command	Displays help menu with interactive commands
/shops admin	shopshelves.admin	Toggles Admin Mode to bypass restrictions
/shops reload	shopshelves.reload	Reloads all configuration and pricing files
/shops update	shopshelves.update	Forces a global re-render of text displays
/shops mode [mode]	shopshelves.mode	Sets message target (CHAT/ACTIONBAR) or price style
/shops itemprice	shopshelves.itemprice	Inspects global price settings for held item
/shops itemprice <price> <type> <amount>	shopshelves.itemprice	Sets global price for held item
/shops price <price> <type> <amount>	shopshelves.price	Creates a temporary custom price stamp on held item

---

🔑 Permissions

• shopshelves.command — Access to /shops help command (Default: Everyone)
• shopshelves.admin — Access to /shops admin mode (OP Level 2)
• shopshelves.reload — Access to /shops reload (OP Level 2)
• shopshelves.update — Access to /shops update (OP Level 4)
• shopshelves.mode — Access to /shops mode (OP Level 4)
• shopshelves.itemprice — Manage global item pricing (OP Level 2)
• shopshelves.price — Create custom item price stamps (OP Level 2)
• shopshelves.playershelf — Permission to create PlayerShelves (Default: Everyone)
• shopshelves.playershelves.unlimited — Unlimited PlayerShelf creation (OP Level 4)
• shopshelves.playershelves.<number> — Sets custom shelf limit (e.g. shopshelves.playershelves.10)
• shopshelves.setlabel — Set custom floating shop labels (OP Level 2)
• shopshelves.setlabel.color — Use color/hex formatting in labels (OP Level 4)

---

🛠️ Developer API

For mod developers, ShopShelves exposes internal shop shelf methods 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 final class ShopshelvesApi {

    private static final ShopshelvesApi INSTANCE = new ShopshelvesApi();

    private ShopshelvesApi() {}

    public static ShopshelvesApi getInstance() {
        return INSTANCE;
    }

    // Checks if a given BlockEntity is an active ShopShelf.
    public boolean isShopShelf(@Nullable BlockEntity blockEntity) {
        if (!(blockEntity instanceof ShelfBlockEntity) || !(blockEntity instanceof ShopShelf shopShelf)) {
            return false;
        }
        return shopShelf.getShopMode() != ShopHelper.ShopMode.NONE;
    }

    // Gets the current shop mode for a BlockEntity.
    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 shop owner.
    public Optional<UUID> getShopOwner(@Nullable BlockEntity blockEntity) {
        if (blockEntity instanceof ShopShelf shopShelf && isShopShelf(blockEntity)) {
            return shopShelf.getOwner();
        }
        return Optional.empty();
    }
}

---

💬 Support & Contact Policy

Primary Support (Discord)

All questions, bug reports, and suggestions should go through our Official Discord Server so other community members can find existing solutions.

Urgent PM Policy

Direct private messages are reserved for critical production emergencies:

• Allowed Reason: Severe server crashes or critical item exploits directly caused by the mod.
• Requirement: Must be the server owner/administrator.
• Hours: 10:00 AM – 10:00 PM CET (Brussels Time).

---

📜 Modpack Policy

• ✅ You are welcome to include ShopShelves in public or private modpacks.
• ❌ Direct redistribution or re-hosting behind a paywall is prohibited.