s8n/minecraft-server
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
minecraft-server/docs/SHOP-SYSTEM-DECISION.md

8.1 KiB
Raw Permalink Blame History

Shop System Decision — racked.ru

Date: 2026-05-07 Author: s8n Status: Decision — supersedes AUDIT-2026-05-07 F-11 Inputs: RESEARCH-SHOP-GUI.md (S1), RESEARCH-AUCTION-HOUSE.md (S2), RESEARCH-SHOP-AH-HYBRID.md (S3)

1. Problem statement

Three things land on the same hot spot:

  • EZShop is bespoke, hardcoded 27-slot, drop+click-only, ugly title — YOU500 wants 54-slot polish.
  • AuctionHouse 1.4.6 (Kiranhart) works, but ships ARR with no LICENSE file and a recurring dupe history.
  • We want a single coherent marketplace experience under /pm (canonical exec), not a salad of mismatched plugins.

Three agents researched independently. They disagree on the shape of the answer:

Agent Recommendation Core argument
S1 (shop GUI) EconomyShopGUI free + keep AH separate Best free-tier shop UX, drop-in replacement
S2 (auction house) Keep Kiranhart short-term, swap to Nexus or Elaine Qheart License + dupe risk; UX parity in the GPL fork
S3 (hybrid) ExcellentShop unified, GPL-3 One jar, one theme, one update path

This doc reconciles them.

2. Stack candidates side-by-side

Stack Plugins Shop license AH license Unified GUI? Player shops? Dependency surface
A. ExcellentShop unified ExcellentShop + CoinsEngine (or Vault bridge) + NightCore GPL-3 GPL-3 Shared theme, separate menus Optional Chest module NightCore framework jar
B. EconomyShopGUI + NexusAuctionHouse EconomyShopGUI free + NexusAH Proprietary free-tier MIT No (two themes) No Vault
C. Genesis (BSP) + Elaine Qheart AH Genesis + AuctionHousePlugin MIT GPL No Genesis addon Vault
D. Status quo EZShop + AuctionHouse 1.4.6 Bespoke (us) ARR no LICENSE No No Vault

3. License + project-health matrix

Stack License fit (AGPL-leaning) Active? 1.21.x verified Dupe / exploit history FOSS-ethics score
A. ExcellentShop GPL-3, sources self-buildable Yes — push 2026-04-27 1.21.8+ Java 21 Clean 5/5
B. EconomyShopGUI + Nexus Proprietary free + MIT Both active; Nexus quieter 1.21.11 / 1.21.6 Clean 3/5
C. Genesis + Elaine MIT + GPL Genesis active; Elaine open beta 1.21.1 (Genesis untested 1.21.4+) Clean 5/5
D. Status quo Bespoke + ARR EZShop dead-bespoke; Kiranhart active 1.21.x Recurring dupes (AntiDupe band-aid exists) 1/5

ExcellentShop is the only stack where both halves are GPL-3, both are actively maintained by the same dev (NightExpress), and source is self-buildable so we never ship a paywalled binary. Everything else either splits the license story across two projects or carries one proprietary half.

4. Visual mockup — recommended /pm shop GUI

ExcellentShop's Virtual Shop module, themed and aliased. Title kept clean per YOU500 ask.

+------------------------------------------------------------+
|                  racked.ru / pm shop                       |
+------------------------------------------------------------+
|  [BLK]  [ORE]  [FOO]  [MOB]  [RED]  [DYE]  [TLS]  [MSC]    |   <- 8 categories
|                                                            |
|  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]               |
|  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]               |   <- 36 item slots
|  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]               |      (4 rows x 9)
|  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]  [ ]               |
|                                                            |
|  [<]    [SELLALL]    [/pm market]    [BAL: 1,234]   [>]    |   <- nav + AH jump
+------------------------------------------------------------+

54 slots total: 8 category icons (top), 36 items (4x9 grid), 9 footer (page nav, sellall shortcut, AH cross-link, balance, page indicator). Right-click any item = sell, left-click = buy. No donor stars, no rank-locked items in the default tier.

/pm market opens the shared-theme Auction House (ExcellentShop AH module) in the same skin, same fonts, same border palette — the polish unification S3 was after.

5. Recommendation — Stack A (ExcellentShop unified)

Pick ExcellentShop + CoinsEngine.

Why this beats S1's EconomyShopGUI:

  • EconomyShopGUI's free tier is genuinely good for the shop but the auction module is paywalled. S1 was right that the shop is excellent; S1 was wrong to treat AH as out-of-scope, because we already need to swap Kiranhart (S2's finding). If we have to touch both anyway, replacing both with one GPL plugin beats replacing both with two unrelated plugins.
  • "Free binary, closed source" is exactly the trap our philosophy memo (project_racked_philosophy.md) tells us to avoid when a real GPL alternative exists at parity.

Why this beats S2's Nexus / Elaine path:

  • Nexus is BIN-only (no bidding). Players already use bidding on Kiranhart; removing it is a regression.
  • Elaine Qheart's plugin is open beta with ~1k installs. The license is right, the maturity is not.
  • ExcellentShop's AH module has BIN+bid+per-rank caps+tax — feature-parity with Kiranhart, GPL license, single-vendor support story.

S3 was directionally right. The fix vs S3 is mostly operational (alias commands under /pm, disable Chest module, build from source).

6. Migration cost

Step Effort Risk
1. Build ExcellentShop + CoinsEngine + NightCore from source on a builder pod 1 evening Low — mvn package, output jars
2. Stage on dev container, replicate EZShop 8 categories into virtual-shop/ YAML 2-3 hours Low — YAML, no schema gotchas
3. Migrate AuctionHouse listings Cannot migrate active listings — drain or expire current AH first; new AH starts empty Medium — communicate to players
4. Alias /pm shop → /vshop, /pm market → /ah, hide native cmds 30 min via commands.yml Low
5. Disable Chest Shop module (we don't need it; QuickShop-Hikari is the future story) 5 min config flag None
6. Smoke-test on staging: 54-slot layout, per-rank discount perms, sellall, AH listing+bid Half day Low
7. Maintenance-window swap on live: stop server, drop EZShop+AuctionHouse jars, drop new jars, reload configs 30 min downtime Medium — see risk register
8. Update AUDIT-2026-05-07.md F-11, update /pm help, post player notice 1 hour None

Total: roughly one evening of build+stage + one half-day staging trial + one short maintenance window. No code changes to other plugins. AuthLimbo, chat plugin, LP prefixes — all untouched.

7. Risk register

Risk Likelihood Impact Mitigation
ExcellentShop GPL build breaks on a future Paper API rev Low Medium Pin a known-good tag; CI build on Forgejo runner
NightCore framework jar drift between ExcellentShop and CoinsEngine Low Medium Lock both to the same release wave; smoke-test on each upgrade
Player backlash over draining current AH listings Medium Low Two-week heads-up in /pm news; offer to refund stuck items manually
/pm alias collisions with existing chat plugin commands Low Low Audit /pm namespace before swap; document in SYSTEM.md
ExcellentShop dev (NightExpress) goes dark Low High Source is GPL-3 — we keep buildable copy; fall back to Stack C (Genesis + Elaine) only if needed
Per-rank discount permissions clash with LP prefixes-locked rule Low Low Discount perms ride on rank perms, not prefix metadata — orthogonal to feedback_lp_prefixes_locked.md
YOU500-style player wants bidding back in identical Kiranhart UX Medium Low ExcellentShop AH supports bid+BIN; theme tweaks deliver familiar feel
Build-from-source policy adds ops overhead Certain Low Document in nullstone-server/build-shop.md; one-line mvn package script

8. Decision

Adopt Stack A — ExcellentShop unified, GPL-3, built from source. Schedule the migration after the next AuthLimbo release window. Update audit F-11 to reference this doc. Keep S1's EconomyShopGUI and S2's Nexus / Elaine in the back pocket as fallbacks if ExcellentShop ever goes dark.