ShopShelves

ShopShelves - Admin Shops & Player-Owned Shops

The Plugin version can be read about at the SpigotMc page.

ShopShelves transforms the new Shelf Block (added in Minecraft 1.21.9) into flexible, server-friendly shops! This powerful server-side Fabric mod for Minecraft 1.21.9 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 ingame shelf blocks in order:

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

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

Custom Price GUI — shift right-click a shelf to set custom prices per slot.

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

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 ShopshelvesApi() {}

    public static ShopshelvesApi getInstance() {
        return INSTANCE;
    }

    /**
     * Checks if a given BlockEntity is an active ShopShelf (any mode other than NONE).
     */
    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, if it is an active ShopShelf.
     */
    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.
     */
    public Optional<UUID> getShopOwner(@Nullable BlockEntity blockEntity) {
        if (blockEntity instanceof ShopShelf shopShelf && isShopShelf(blockEntity)) {
            return shopShelf.getOwner();
        }
        return Optional.empty();
    }
}

Required Mod: EcoBal Economy API

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. Admin shops are never restricted by the world allowlist and cannot be broken from the front face's 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 type across all three slots with a shared price, or allow each slot to hold a different item independently.
  • Limits player shop creation based on permission nodes and a configurable default limit.
  • When the linked container is broken, the player shelf automatically resets to a plain vanilla shelf — no leftover floating text or stale data.

Custom Shop Labels

• Shop owners and admins can set a custom floating label on any shelf via the Price GUI.
• Labels support legacy color codes (&c, &l, etc.), hex color codes (&#RRGGBB), and a newline marker (\n or &n) to split the label across two lines.
• Surrounding spaces around \n / &n are stripped automatically.
• The length limit (label_max_length in config.yml, default 64) counts only visible characters — color codes and the newline marker are ignored entirely.
• Bracket formatting for both admin and player shelf labels is fully configurable per type in messages.yml, including open/close bracket text, color, and a brackets_per_line toggle:
  • true (default) — brackets wrap every line.
  • false — opening bracket on the first line only, closing bracket on the last line only.
• Right-click the label button in the Price GUI to clear the label instantly, without closing the GUI.

Dynamic Item Pricing

• Global Pricing (pricing.yml): Set default buy and sell prices for items, including data-rich items like potions, enchanted books, goat horns, and player heads.
• Custom Price Stamps: Use the /shops price command to apply a one-time price stamp to a held item. That item can then configure a PlayerShelf or 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; the shop calculates the correct unit price per transaction.
• In-GUI Price Editing: Shift right-click any shelf to open the Price GUI and adjust buy/sell prices with increment/decrement buttons or by typing an exact value in chat.
• Price Reset: Reset any slot's custom price back to config defaults from within the Price GUI. In single-type mode, resetting clears all three slots at once with a clean, slot-agnostic confirmation message.

Statistics Book

• Open the Stats Book from the viewer GUI or the price GUI to see a full breakdown of total money earned and lost per slot for both Admin Shops and Player Shelves.
• Profit and loss are tracked separately per slot and persist through server restarts.

Advanced Text Display & Aesthetics

• Dynamic Floating Text: Shop information is displayed using Minecraft Text Display Entities, which automatically update when stock changes, prices are modified, or a shop goes "Out of Order."
• Customizable Scaling: Configure the scale 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 display and the price display.
• Two Price Display Modes:
  • TRIPLEPRICE: Shows the price per slot — ideal for multi-item Admin Shops.
  • SINGLEPRICE: Shows one merged price for the shelf — forced for Player Shelves.
• Rich Text Formatting: All display text and chat messages support legacy color codes and hex color codes throughout.
• Item Language: Localize item names in displays using any Minecraft locale (en_us, de_de, fr_fr, etc.), fetched asynchronously from GitHub on startup.

Shop Management & Protection

• Player Shop Limits: Restrict the number of PlayerShelves a player can create using permission nodes (e.g., shopshelves.playershelves.5 for a limit of 5) or grant unlimited creation.
• World Allowlist: Restrict player shop creation to specific worlds. Admin shops are never affected by this list.
• Admin Mode: Operators enter a special "Admin Mode" (/shops admin) to bypass all shop protections and quickly configure shops.
• Break Protection: The front-face item slots of both Admin Shops and Player Shelves cannot be broken by clicking within the 8×16 pixel slot area — owners and admins must target the top or bottom band of the shelf face to break it.
• Container Protection: Linked containers are protected from non-owners and cannot be broken while linked to a PlayerShelf.
• Explosion Immunity: Shop shelves and their linked containers are immune to TNT, creepers, fireballs, and wither explosions.
• Config Auto-Migration: On every startup, both config.yml and messages.yml are automatically updated to add any new keys introduced in an update — old config files are never broken or reset.
• 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 worlds.

Commands

• /shops, /shopshelves — Displays the main help page with clickable commands.
• /shops admin — Toggles admin mode to bypass shop protection and 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 (CHAT | ACTIONBAR | BOTH) or Price Display Mode (SINGLEPRICE | TRIPLEPRICE).

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.
  • <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 stamped item is allowed in a player's inventory at a time.

Permissions

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.