Описание
## **ShopShelves - Admin Shops & Player-Owned Shops**
Using Bukkit Spigot Paper or Purpur?
To get the most accurate list of features and general information please visit the Spigot site:
[The Plugin version can be read about at the SpigotMc page.](https://www.spigotmc.org/resources/shopshelves.130230/)
[Client side mod that improves the shopping experience!! WIITS](https://modrinth.com/mod/wiits)
[](https://modrinth.com/mod/wiits)
**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.)
     
 
📧 Contact Me & Support Information
### 💬 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](https://discord.gg/48sZCbdHzJ).** 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!
---
🛠️ API Integration Guide: The ShopshelvesApi
For mod developers, **ShopShelves** exposes shop shelf functions via the `ShopshelvesApi` class.
```java
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 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 getShopOwner(@Nullable BlockEntity blockEntity) {
if (blockEntity instanceof ShopShelf shopShelf && isShopShelf(blockEntity)) {
return shopShelf.getOwner();
}
return Optional.empty();
}
}
```
[](https://modrinth.com/mod/ecobal) **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 ` — Sets the global price for the held item.
* ``: `buy`, `sell`, or `both`
* ``: The quantity the price applies to (e.g., `64`)
### Custom Price Stamp Command (Requires `shopshelves.price`):
* `/shops price ` — 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
Click to view all permission nodes and their descriptions
* `shopshelves.command` — Access to the base `/shops` help command. *(Default: all players)*
* `shopshelves.admin` — Usage of `/shops admin` mode. *(OP Level 2)*
* `shopshelves.reload` — Usage of `/shops reload`. *(OP Level 2)*
* `shopshelves.update` — Usage of `/shops update`. *(OP Level 4)*
* `shopshelves.mode` — Usage of `/shops mode`. *(OP Level 4)*
* `shopshelves.itemprice` — Usage of `/shops itemprice` to manage global pricing. *(OP Level 2)*
* `shopshelves.price` — Usage of `/shops price` to create custom price stamps. *(OP Level 2)*
* `shopshelves.playershelf` — Allows a player to create PlayerShelves. *(OP Level 0 by default)*
* `shopshelves.playershelves.unlimited` — Grants unlimited PlayerShelf creation. *(OP Level 4)*
* `shopshelves.playershelves.` — Sets the maximum number of PlayerShelves a player can own (e.g., `shopshelves.playershelves.10` for a limit of 10). *(OP Level 2)*
* `shopshelves.setlabel` — Allows setting a custom label on a shop. *(OP Level 2)*
* `shopshelves.setlabel.color` — Allows using color codes and hex colors in custom labels. *(OP Level 4)*
---
## 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**.