minecraft-server/docs/RESEARCH-SHOP-GUI.md

# RESEARCH: GUI Shop Plugin Replacement for EZShop

**Date:** 2026-05-07
**Server:** racked.ru (Paper 1.21.x)
**Current state:** EZShop 1.0-SNAPSHOT (custom, hardcoded 27 slots, drop+click sell only). YOU500 player report wants 54 slots + cleaner title. AUDIT-2026-05-07 F-11 already flags EZShop for removal.
**Goal:** polished default-player sell/buy GUI with categories, multi-page, per-rank pricing, AGPL-compatible.

---

## Candidates Evaluated

### 1. EconomyShopGUI (free) — Gypopo
- **Status:** very active; v6.16.2 supports MC 1.21.11 (May 2026 release).
- **License:** proprietary "free to use" binary; only the API is open-source on GitHub. **Not AGPL-compatible** in source-distribution sense, but redistributable as plugin.
- **Stack:** Bukkit/Spigot/Paper; uses Paper API on modern servers; MiniMessage support since 6.14.
- **1.21.x compat:** verified through 1.21.11.
- **Paradigm:** admin shop, both buy and sell, no player shops.
- **GUI:** sizes 9-54 configurable; multi-page; categories with custom icons; clean titles per category.
- **Categories:** unlimited (Blocks, Redstone, Food, Mob Drops…); /sellgui sub-menu; /sellall.
- **Vault:** yes; also PlayerPoints, CoinsEngine, GemsEconomy, UltraEconomy, zEssentials, VotingPlugin.
- **Per-rank pricing:** yes — discount/sell-multiplier permission nodes (`EconomyShopGUI.discount.<n>`).
- **Config:** YAML-only in free; in-game GUI editor is premium-locked. Wiki at `wiki.gpplugins.com`.
- **DiscordSRV:** none directly; via PAPI placeholders + DiscordSRV chat-broadcast feasible.
- **Known bugs:** historic Paper-meta color-code raw display (fixed 6.x); permission registration on Paper plugin module (fixed); Mojang skull texture API outages; reviews otherwise overwhelmingly positive.
- **Premium gates:** dynamic pricing, per-player limits, NBT/custom items, MySQL stock sync, command items, in-game GUI editor, search bar, EXP-locked items.
- **Verdict:** **STEAL** — drop-in replacement that solves every YOU500 complaint with the free tier. Premium gates are nice-to-haves we don't need.

### 2. Genesis (formerly BossShopPro) — MageMonkey.studio
- **Status:** actively maintained fork after Blackixx abandoned BSP; 1.21.1 released; 405 commits on dev branch.
- **License:** MIT (verified on GitHub repo `magemonkeystudio/genesis`). **AGPL-compatible.**
- **Stack:** Spigot/Paper.
- **1.21.x compat:** 1.21.1 confirmed, no explicit 1.21.4+ tag yet — needs smoke test.
- **Paradigm:** generic GUI engine (not strictly a shop); buy/sell/conditions/rewards all configurable.
- **GUI:** any size 9-54, multi-page, full title control.
- **Categories:** modeled as nested menus (manual link buttons); no built-in category abstraction.
- **Vault:** yes; addon `Multiple Currencies` for points/tokens.
- **Per-rank pricing:** yes via condition system + permission predicates.
- **Config:** YAML, very verbose — every button hand-defined. High config complexity but maximum flexibility.
- **Addons:** Player Shops, Limited Uses, Inventory Commands, Multiple Currencies (all free).
- **DiscordSRV:** none native; PAPI bridge possible.
- **Known bugs:** original BSP broke on 1.21 with old maintainer absent; Genesis fork stable but skull-texture fixes still trickling in.
- **Verdict:** **PATTERN** — too DIY for a default-player shop, but the condition/predicate model is the gold standard if we ever need a quest-shop or rank-buy GUI. Keep in pocket.

### 3. UltimateShop — PQguanfang / ManyouTeam
- **Status:** very active; supports 1.20.5–1.21.11.
- **License:** GPL-3 (from search results) but a "Plugin EULA" clause restricts redistribution on leaked-plugin sites. Effectively GPL-3 + non-commercial-clone clause. **AGPL-compatible for our use** (we don't redistribute).
- **Stack:** Paper-first.
- **1.21.x compat:** verified to 1.21.11.
- **Paradigm:** admin shop; buy/sell; daily-rotation shop; menu-as-shop hybrid (TrMenu-inspired).
- **GUI:** fully customizable slot layout, multi-page native.
- **Categories:** yes; menu-driven with NBT-aware item display.
- **Vault:** yes; also PlayerPoints, plus item-for-item barter.
- **Per-rank pricing:** yes — conditional pricing with PAPI math expressions (e.g. VIP discount via placeholder).
- **Config:** YAML + math expressions; mid complexity; integrates with MMOItems, Oraxen, Nexo, MythicMobs.
- **DiscordSRV:** none mentioned.
- **Known bugs:** none flagged in search; some advanced features paywalled.
- **Verdict:** **STEAL (alternate)** — strong second pick if EconomyShopGUI's premium-funnel becomes an issue. Slightly steeper config, but cleaner license story.

### 4. QuickShop-Hikari — Community fork
- Active, 6.2.0.11 (Feb 2026). Dual GPLv3 / AGPLv3 — perfect license fit. Paper-only (Spigot dropped). 1.20+ verified.
- Paradigm: **player chest shops** — wrong fit for "default-player sell shop". Also has admin-shop mode but the UX is sign+chest, not category GUI.
- MiniMessage native, NBT, virtual displays.
- **Verdict:** **PATTERN** — keep for future "player shops at spawn" feature; not a replacement for EZShop.

### 5. ChestShop-3 (Acrobot)
- LGPL-2.1, dev-builds work on 1.21.8 but last tagged release was 2022. Sign+chest paradigm — no GUI.
- **Verdict:** **SKIP** — wrong paradigm and stale tags.

### 6. zShop — Maxlego08 / GroupeZ
- GPL-3 — AGPL-compatible. Active (396 commits). Spigot-targeted.
- Buy/sell/permissions/enchants/orders. 17 button types. Multi-economy.
- 1.21 compat unclear from search; relies on zMenu API dep (extra plugin to install).
- **Verdict:** **PATTERN** — interesting for the order-book idea but extra dependency and unclear 1.21 status make it second-tier.

### 7. CoinsEngine + ExcellentShop (NightExpress)
- CoinsEngine 1.20–1.21.10, free, modular currency provider.
- ExcellentShop is the shop module; modular (virtual / chest / rotating sub-shops); paid premium for full feature set, free tier limited.
- **Verdict:** **SKIP** for shop (paid funnel mirrors ShopGUI+); CoinsEngine itself is worth noting as a Vault alternative if we ever need multi-currency.

### 8. ShopGUI+ (brcdev)
- Paid only on SpigotMC; closed source. Popular but **fails AGPL/free preference**.
- **Verdict:** **SKIP**.

### 9. DeluxeMenus (HelpChat)
- MIT, active, 1.21 compat. **Not a shop** — generic menu engine. No economy logic; you'd glue Vault commands manually.
- **Verdict:** **PATTERN** — already used elsewhere on racked.ru; worth using as the *frontend* for a hand-rolled shop only if all of the above fail.

### 10. AuctionHouse (kiranhart) / NexusAuctionHouse / ModernHDV
- Already deployed (`AuctionHouse-1.4.6.jar`). **Player-to-player auction**, not category sell-shop. Complementary, not substitute. F-11 was wrong to call AuctionHouse a replacement — it solves a different problem.
- **Verdict:** keep AuctionHouse; do **not** rely on it as the EZShop replacement.

---

## Recommendation

**Top 3:**
1. **EconomyShopGUI (free)** — STEAL. Best fit, zero-config defaults, every YOU500 complaint resolved out of the box.
2. **UltimateShop** — STEAL alternate. Cleaner license, comparable feature set, slightly more config.
3. **Genesis (BSP-continued)** — PATTERN. Keep in pocket for advanced quest-shop / rank-gated GUIs.

**Action:** Pilot EconomyShopGUI free on staging, replicate current EZShop categories, smoke-test 54-slot layout, ship to live in next maintenance window. Keep AuctionHouse separate (player auctions remain a distinct feature). Update `AUDIT-2026-05-07.md` F-11 to reflect that EconomyShopGUI — not AuctionHouse — is the replacement.
-												docs: shop system research + decision (ExcellentShop or split)

											
										
										
											2026-05-07 22:35:28 +01:00
+								# RESEARCH: GUI Shop Plugin Replacement for EZShop
 								**Date:** 2026-05-07
 								**Server:** racked.ru (Paper 1.21.x)
 								**Current state:** EZShop 1.0-SNAPSHOT (custom, hardcoded 27 slots, drop+click sell only). YOU500 player report wants 54 slots + cleaner title. AUDIT-2026-05-07 F-11 already flags EZShop for removal.
 								**Goal:** polished default-player sell/buy GUI with categories, multi-page, per-rank pricing, AGPL-compatible.
 								---
 								## Candidates Evaluated
 								### 1. EconomyShopGUI (free) — Gypopo
 								- **Status:** very active; v6.16.2 supports MC 1.21.11 (May 2026 release).
 								- **License:** proprietary "free to use" binary; only the API is open-source on GitHub. **Not AGPL-compatible** in source-distribution sense, but redistributable as plugin.
 								- **Stack:** Bukkit/Spigot/Paper; uses Paper API on modern servers; MiniMessage support since 6.14.
 								- **1.21.x compat:** verified through 1.21.11.
 								- **Paradigm:** admin shop, both buy and sell, no player shops.
 								- **GUI:** sizes 9-54 configurable; multi-page; categories with custom icons; clean titles per category.
 								- **Categories:** unlimited (Blocks, Redstone, Food, Mob Drops…); /sellgui sub-menu; /sellall.
 								- **Vault:** yes; also PlayerPoints, CoinsEngine, GemsEconomy, UltraEconomy, zEssentials, VotingPlugin.
 								- **Per-rank pricing:** yes — discount/sell-multiplier permission nodes (`EconomyShopGUI.discount.<n>`).
 								- **Config:** YAML-only in free; in-game GUI editor is premium-locked. Wiki at `wiki.gpplugins.com`.
 								- **DiscordSRV:** none directly; via PAPI placeholders + DiscordSRV chat-broadcast feasible.
 								- **Known bugs:** historic Paper-meta color-code raw display (fixed 6.x); permission registration on Paper plugin module (fixed); Mojang skull texture API outages; reviews otherwise overwhelmingly positive.
 								- **Premium gates:** dynamic pricing, per-player limits, NBT/custom items, MySQL stock sync, command items, in-game GUI editor, search bar, EXP-locked items.
 								- **Verdict:** **STEAL** — drop-in replacement that solves every YOU500 complaint with the free tier. Premium gates are nice-to-haves we don't need.
 								### 2. Genesis (formerly BossShopPro) — MageMonkey.studio
 								- **Status:** actively maintained fork after Blackixx abandoned BSP; 1.21.1 released; 405 commits on dev branch.
 								- **License:** MIT (verified on GitHub repo `magemonkeystudio/genesis`). **AGPL-compatible.**
 								- **Stack:** Spigot/Paper.
 								- **1.21.x compat:** 1.21.1 confirmed, no explicit 1.21.4+ tag yet — needs smoke test.
 								- **Paradigm:** generic GUI engine (not strictly a shop); buy/sell/conditions/rewards all configurable.
 								- **GUI:** any size 9-54, multi-page, full title control.
 								- **Categories:** modeled as nested menus (manual link buttons); no built-in category abstraction.
 								- **Vault:** yes; addon `Multiple Currencies` for points/tokens.
 								- **Per-rank pricing:** yes via condition system + permission predicates.
 								- **Config:** YAML, very verbose — every button hand-defined. High config complexity but maximum flexibility.
 								- **Addons:** Player Shops, Limited Uses, Inventory Commands, Multiple Currencies (all free).
 								- **DiscordSRV:** none native; PAPI bridge possible.
 								- **Known bugs:** original BSP broke on 1.21 with old maintainer absent; Genesis fork stable but skull-texture fixes still trickling in.
 								- **Verdict:** **PATTERN** — too DIY for a default-player shop, but the condition/predicate model is the gold standard if we ever need a quest-shop or rank-buy GUI. Keep in pocket.
 								### 3. UltimateShop — PQguanfang / ManyouTeam
 								- **Status:** very active; supports 1.20.5–1.21.11.
 								- **License:** GPL-3 (from search results) but a "Plugin EULA" clause restricts redistribution on leaked-plugin sites. Effectively GPL-3 + non-commercial-clone clause. **AGPL-compatible for our use** (we don't redistribute).
 								- **Stack:** Paper-first.
 								- **1.21.x compat:** verified to 1.21.11.
 								- **Paradigm:** admin shop; buy/sell; daily-rotation shop; menu-as-shop hybrid (TrMenu-inspired).
 								- **GUI:** fully customizable slot layout, multi-page native.
 								- **Categories:** yes; menu-driven with NBT-aware item display.
 								- **Vault:** yes; also PlayerPoints, plus item-for-item barter.
 								- **Per-rank pricing:** yes — conditional pricing with PAPI math expressions (e.g. VIP discount via placeholder).
 								- **Config:** YAML + math expressions; mid complexity; integrates with MMOItems, Oraxen, Nexo, MythicMobs.
 								- **DiscordSRV:** none mentioned.
 								- **Known bugs:** none flagged in search; some advanced features paywalled.
 								- **Verdict:** **STEAL (alternate)** — strong second pick if EconomyShopGUI's premium-funnel becomes an issue. Slightly steeper config, but cleaner license story.
 								### 4. QuickShop-Hikari — Community fork
 								- Active, 6.2.0.11 (Feb 2026). Dual GPLv3 / AGPLv3 — perfect license fit. Paper-only (Spigot dropped). 1.20+ verified.
 								- Paradigm: **player chest shops** — wrong fit for "default-player sell shop". Also has admin-shop mode but the UX is sign+chest, not category GUI.
 								- MiniMessage native, NBT, virtual displays.
 								- **Verdict:** **PATTERN** — keep for future "player shops at spawn" feature; not a replacement for EZShop.
 								### 5. ChestShop-3 (Acrobot)
 								- LGPL-2.1, dev-builds work on 1.21.8 but last tagged release was 2022. Sign+chest paradigm — no GUI.
 								- **Verdict:** **SKIP** — wrong paradigm and stale tags.
 								### 6. zShop — Maxlego08 / GroupeZ
 								- GPL-3 — AGPL-compatible. Active (396 commits). Spigot-targeted.
 								- Buy/sell/permissions/enchants/orders. 17 button types. Multi-economy.
 								- 1.21 compat unclear from search; relies on zMenu API dep (extra plugin to install).
 								- **Verdict:** **PATTERN** — interesting for the order-book idea but extra dependency and unclear 1.21 status make it second-tier.
 								### 7. CoinsEngine + ExcellentShop (NightExpress)
 								- CoinsEngine 1.20–1.21.10, free, modular currency provider.
 								- ExcellentShop is the shop module; modular (virtual / chest / rotating sub-shops); paid premium for full feature set, free tier limited.
 								- **Verdict:** **SKIP** for shop (paid funnel mirrors ShopGUI+); CoinsEngine itself is worth noting as a Vault alternative if we ever need multi-currency.
 								### 8. ShopGUI+ (brcdev)
 								- Paid only on SpigotMC; closed source. Popular but **fails AGPL/free preference**.
 								- **Verdict:** **SKIP**.
 								### 9. DeluxeMenus (HelpChat)
 								- MIT, active, 1.21 compat. **Not a shop** — generic menu engine. No economy logic; you'd glue Vault commands manually.
 								- **Verdict:** **PATTERN** — already used elsewhere on racked.ru; worth using as the *frontend* for a hand-rolled shop only if all of the above fail.
 								### 10. AuctionHouse (kiranhart) / NexusAuctionHouse / ModernHDV
 								- Already deployed (`AuctionHouse-1.4.6.jar`). **Player-to-player auction**, not category sell-shop. Complementary, not substitute. F-11 was wrong to call AuctionHouse a replacement — it solves a different problem.
 								- **Verdict:** keep AuctionHouse; do **not** rely on it as the EZShop replacement.
 								---
 								## Recommendation
 								**Top 3:**
 . **EconomyShopGUI (free)** — STEAL. Best fit, zero-config defaults, every YOU500 complaint resolved out of the box.
 . **UltimateShop** — STEAL alternate. Cleaner license, comparable feature set, slightly more config.
 . **Genesis (BSP-continued)** — PATTERN. Keep in pocket for advanced quest-shop / rank-gated GUIs.
 								**Action:** Pilot EconomyShopGUI free on staging, replicate current EZShop categories, smoke-test 54-slot layout, ship to live in next maintenance window. Keep AuctionHouse separate (player auctions remain a distinct feature). Update `AUDIT-2026-05-07.md` F-11 to reflect that EconomyShopGUI — not AuctionHouse — is the replacement.