NormalShops — Player & admin guide

Thanks to https://github.com/Clickism/ClickShop - Clickism

In-world shop (storefront)

Villager Menus used as trading

Custom display: item showcase, glass/base blocks, and optional sale-style floating text.

/shops — public shop browser

Paginated list of in-stock shops; click entries to teleport (when enabled).

GUI overview (main menus)

Create/change listing, owner panel, access chooser, buy flow, stock, settings, and more.

Admin / delete hub (shift + right-click)

Force edit, force change owner, delete, history, emulate sale — sensitive actions require op in addition to normalshops.delete.

Creating a shop (walkthrough)

GIF: interact with an empty chest/barrel with a sign, set price and products, and open for business. (Exact flow matches your server’s messages and GUI version.)

Metrics

---

Why NormalShops?

NormalShops turns chests and barrels into fully interactive player shops without forcing players through obscure commands. Owners get a polished editor, buyers get a clear purchase flow (classic GUI or villager-style trading), and staff get real tools — history, emulation, ownership transfer — backed by optional CoreProtect integration.

Whether you run a survival economy or a mini-game hub, NormalShops is built to feel native to Minecraft: signs, chests, sounds, and inventories players already understand.

---

Feature overview

Core shop experience Capability Description Block-based shops Create shops on chests or barrels using a sign (any sign type). The container must be empty and not a double chest. Price & products Set a currency item (and amount) plus one or more products — including custom items, heads, and NBT-heavy goods when full-nbt-check is enabled. Buy flow Customers use either a Buy GUI or a villager merchant interface (configurable via villager-trading-menu). Stockpiles Link remote chest inventories so sold items pull from real storage — with per-shop limits and optional stockpile protection. Earnings Sales credit internal earnings; owners withdraw through a paged earnings chest (partial pickups, stacked bundles). Custom displays Glass and item-frame style shop displays, themes, colors, and optional sale text on glass. Sounds & themes Per-shop buy sounds and menu color themes for personality.

Owner & team tools Capability Description Trusted players Grant trusted access so helpers can manage stock and settings without owning the shop. Access choice menu Owners/trusted users pick Editor vs customer trade view so they can preview exactly what buyers see. Unlimited internal stock Internal stock is not capped at 27 slots — use paged stock chest editing (45 slots per page + navigation). Lifetime analytics Revenue, sales count, products sold, impressions, stock added/removed, net change, utilization, conversion rate. Buyer insights Unique buyers and top buyers derived from real purchase history. Market comparison See how other shops price overlapping products and open a paginated competitor list. Shop info card Quick stats lore in the editor (including total impressions).

---

Detailed feature guide

Creating & editing shops

1. Hold any sign and right-click an empty chest or barrel (not sneaking, not a double chest) to open the creation GUI.
2. Place your price (what buyers pay) and products (what they receive) in the designated areas.
3. Click Create Shop to finalize.

Editor controls (create / change product menus):

• Left-click with an item to place it in a slot.
• Right-click with an empty hand to halve the amount in a slot.
• Right-click with the same item as the slot to increase the amount by one.

After creation, right-click your shop block as the owner (or trusted player) to open the access menu: choose Open Editor for management or Open Trade for the buyer-facing experience.

Buying — GUI mode vs villager mode

• villager-trading-menu: true (default): Buyers interact through a merchant window. Multi-product bundles appear as a highlighted chest recipe (contents stored in block state meta) with preview-only rows using a barrier as the fake “price” so the real product stays obvious.
• false: Buyers use the classic BuyMenu chest GUI instead.

Out of stock: Buyers can still open the trade view for transparency. The title reflects stock state (e.g. in stock vs out of stock). For non-admin shops, fulfilling trades is blocked when there is nothing to deliver — no ghost purchases.

Impressions: Opening buy/trade flows can increment lifetime impressions for conversion analytics.

Stock management (paged stock chest)

• Internal stock is stored as a logical list with pagination (45 item slots per page + prev/next/info/back to editor).
• One player at a time may view a shop’s stock GUI to reduce exploit surface.
• Opening stock is blocked while another player has an active villager trade session on that shop (and vice versa).
• Revision counters detect external changes (e.g. a sale while editing) and refresh or invalidate stale views.
• Stockpile-backed removal still integrates with Transaction logic.

Earnings (paged earnings chest)

• Collect opens a dedicated earnings inventory instead of dumping everything into the player’s inventory at once.
• Owners take partial withdrawals; bundles can stack in the GUI for readability.
• The top (earnings) inventory is withdraw-only — players cannot deposit or shift-click into earnings slots; their own inventory remains freely movable.
• Same single-viewer and revision philosophy as stock.

Stockpiles & earnings piles

• Stockpiles: Connect additional chests to supply sold items. Optional protect-stockpiles keeps foreign players from opening linked chests (bypass: normalshops.bypass-stockpile).
• Earnings piles: Central ender chest “banks” that aggregate payouts from multiple shops (subject to limits in config.yml).
• Tethers: Optional particle / rope visualization while linking (visualize-tethers).
• Double chests: Pile locations are canonicalized so left/right halves resolve to one logical pile.

Customization & polish

• Menu colors, custom shop names (length-limited), sale text on displays.
• Frame & glass displays with lights, layering, and “move to top” style controls.
• Per-shop notifications and low-stock warnings in settings.
• Unlimited stock mode exists for special cases (gated behind normalshops.unlimited-stock — intentionally dangerous on economy servers).

Administration & audit trail

Shift + right-click a shop with normalshops.delete to open the admin / delete hub — including on your own shops.

Important: Force edit, force change owner, deleting someone else’s shop, history, and emulate sale require normalshops.delete and server operator (isOp()). Without op, those actions are denied and logged.

Admin control	What it does
Delete shop	Remove the listing (with optional operator earnings collection via operator-delete-shop-collect).
Force edit	Open the full owner editor as staff to adjust price, stock, display, etc.
Force change owner	Prompts for a username in chat; transfers ownership safely via ShopManager.
Shop history	Paginated persistent per-shop log (buys, edits, connects, emulated sales, villager buys, …). Falls back to CoreProtect block lookup when needed.
Emulate sale	Runs a synthetic transaction (stock + earnings + stats + logging) for testing or moderation — tagged distinctly in logs (NormalShops-EmulatedSale).

CoreProtect (optional): If CoreProtect is present and its API is enabled, NormalShops records interaction-style logs for creates, deletes, buys (GUI & villager), stockpile changes, earnings collection, connects/disconnects, and more — while also appending structured lines to in-plugin history for the GUI.

Safety & anti-dupe design

• Editor session lock: Only one management session “owns” deep edits at a time; submenus respect the same lock messaging.
• Management access checks on open and click: if a trusted player is removed while online, GUIs stop accepting actions and can close safely.
• Stock / earnings revisions + exclusive viewers reduce race windows between GUIs, merchants, and async saves.
• Fulfillment checks on villager trades ensure stock is actually removed before counting revenue or sales.

---

Installation

1. Server: Paper or Spigot 1.20.x (API 1.20 as declared in plugin.yml).
2. Java: 17.
3. Drop NormalShops-*.jar into plugins/.
4. Optional: Install CoreProtect for external block history and richer audit trails.
5. Restart once, then tune plugins/NormalShops/config.yml, gui.yml, and language files under plugins/NormalShops/messages/.

---

Quick start

Step	Action
1	Get a sign and right-click an empty chest or barrel (not sneaking).
2	Set price and products in the GUI, then Create Shop.
3	Right-click the shop block to manage or preview the buyer view.
4	Use Stock chest in the editor to add paged internal stock.
5	Use Collect to open the earnings chest and withdraw profits.
6	Link stockpiles / earnings piles from the editor when you outgrow a single block.

---

Permissions

All nodes are prefixed with normalshops..

Permission	Default	Purpose
normalshops.create	true	Create new shops
normalshops.buy	true	Purchase from shops
normalshops.customize	true	Open customization flows
normalshops.display	true	Build advanced displays (needs customize)
normalshops.sale-text	true	Edit floating sale text (needs customize)
normalshops.stockpile	true	Connect stockpiles
normalshops.earnings-pile	true	Connect earnings piles
normalshops.delete	op	Shift-sneak admin hub; dangerous actions also need op
normalshops.bypass-stockpile	op	Open protected foreign stockpiles
normalshops.unlimited-stock	op	Toggle dangerous unlimited stock
normalshops.reload	op	/normalshops reload
normalshops.version	true	/normalshops version (Modrinth compare)
normalshops.viewshops	true	/viewshops, /normalshops view
normalshops.shops	true	/shops browser + teleports
normalshops.region	op	/normalshops region …, /setpoint
normalshops.restore	op	/normalshops restore
normalshops.stats-holograms	op	/normalshops stats-holograms …
normalshops.update-notify	op	Chat when a newer release is on Modrinth
normalshops.coreprotect-test	op	Developer API self-test
normalshops.coreprotect-debug	op	Verbose CoreProtect diagnostics

---

Commands

Command	Description
/normalshops / /nshops	Root: view, reload, version, delete, restore, stats-holograms, region
/normalshops reload	Reload config.yml, gui.yml, and messages
/normalshops version	Jar version + Modrinth update status
/normalshops delete	Look at a shop (≤12 blocks); removes it (permission + staff workflow)
/normalshops restore	Restore from shop-backups.yml onto targeted chest/barrel
/normalshops stats-holograms	list | cleanup private stats displays
/normalshops region	make | cancel — pairs with /setpoint for /shops regions
/viewshops	List your shops + trusted shops; remote open
/shops	Public in-stock browser; optional item filter

For full syntax and defaults, see plugin.yml in the jar or the README command table.

---

Configuration

Key files live in plugins/NormalShops/ (or plugins/ClickShop/ if that legacy folder already exists — data migrates there automatically).

File	Role
config.yml	Language, limits, stockpile protection, piston rules, recovery mode, villager GUI toggle, NBT strictness, distances, display range, /shops regions, backups, …
gui.yml	Menu layouts and icon materials
messages/*.yml	Localizable strings (bundled en_US, de_DE, tr_TR; other codes seed from English)
data.yml + shops/*.yml	Serialized ShopManager, per-player managers, and per-shop files

Highlighted options:

Key	What it controls
language	Message bundle (en_US, de_DE, …).
check-update	Modrinth version check on startup (join notify for ops / update-notify).
protect-stockpiles	Lock foreign access to linked supply chests.
villager-trading-menu	Use merchant UI vs classic buy GUI for customers.
full-nbt-check	Stricter matching for advanced items (economy servers).
max-connection-distance	How far connectors can reach.
shop-limit-per-player / pile limits	Hard caps to protect performance.
recover-shop-files	Emergency resync — auto-disables after one run.

---

Support & contributing

• PRs: Keep changes focused; match existing code style and avoid unrelated refactors.
• Downloads: NormalShops on Modrinth

---