CommunityMarket/servershop/README.md

ServerShop

A professional server-run global market plugin for Paper/Purpur 1.21 using Java 21 and Maven.

ServerShop is designed to complement the CommunityMarket player-to-player marketplace plugin. By maintaining a large spread between buy and sell prices (default: server buys at only 25% of the buy price), the server shop provides an economic safety net while keeping player-to-player trading attractive.

---

Features

• GUI-only — all interactions through clean, paginated GUIs
• Category-based shop — Blocks, Ores, Farming, Food, Mob Drops, Redstone, Decoration, Tools, Combat, Brewing, Misc
• All Minecraft items supported via Material enumeration; unknown/new items fall back to Misc
• Quantity selector — adjust buy/sell quantity in the item detail GUI
• Vault economy integration (required)
• Configurable pricing — per-item and per-category overrides in prices.yml
• Large spread — server buys at 25% of sell price by default (fully configurable)
• i18n — English (en_US) and Portuguese (pt_PT) included; easy to add more
• Optional SQLite transaction logging
• Anti-exploit — shift-click, drag, number-swap events are all cancelled
• Modrinth-ready documentation

---

Requirements

Requirement	Version
Paper / Purpur	1.21+
Java	21+
Vault	Any compatible version
Economy plugin	e.g. EssentialsX, CMI

---

Installation

1. Download ServerShop-<version>.jar from Modrinth / GitHub Releases.
2. Place the JAR in your server's plugins/ folder.
3. Make sure Vault and a compatible economy plugin are installed.
4. Start the server — default config.yml, prices.yml, and language files will be generated.
5. Edit plugins/ServerShop/config.yml and plugins/ServerShop/prices.yml as needed.
6. Run /shop reload (requires servershop.admin.reload) to apply changes without restarting.

---

Commands

Command	Description	Permission
/shop	Opens the main shop GUI	servershop.use
/shop reload	Reloads all configuration	servershop.admin.reload

Aliases: /servershop, /sshop

---

Permissions

Permission	Default	Description
servershop.*	op	All permissions
servershop.use	true	Open the shop
servershop.buy	true	Buy items
servershop.sell	true	Sell items
servershop.admin	op	Admin commands
servershop.admin.reload	op	Reload configuration

---

How Pricing Works (Spread Explanation)

The shop deliberately maintains a large spread between buy and sell prices to keep player-to-player trading in CommunityMarket more economically attractive.

Example with default settings:

Item	Buy Price (player buys)	Sell Price (player sells)	Spread
Diamond	$50.00	$12.50	75%
Iron Ingot	$5.00	$1.25	75%
Wheat	$1.00	$0.25	75%

If a player wants to sell diamonds, they get $12.50 from the server shop. On the CommunityMarket, another player might pay $35–$45 — much more attractive.

Configuring the spread

In config.yml:

pricing:
  global-sell-multiplier: 0.25   # Server pays 25% of buy price (75% spread)

Per-category overrides:

pricing:
  category-sell-multipliers:
    BLOCKS: 0.20    # 80% spread on blocks
    ORES: 0.20      # 80% spread on ores
    FOOD: 0.30      # 70% spread on food

Per-item explicit prices in prices.yml:

categories:
  ORES:
    items:
      DIAMOND:
        buy-price: 50.00
        sell-price: 12.50   # explicit override
      NETHERITE_INGOT:
        buy-price: 500.00
        sell-enabled: false  # cannot sell netherite back to the server

---

How to Edit Categories & Prices

prices.yml structure

categories:
  CATEGORY_NAME:
    display-name: "&7Human Readable Name"
    icon: MATERIAL_NAME          # icon shown in the category GUI
    buy-enabled: true            # can players buy from this category?
    sell-enabled: true           # can players sell to this category?
    items:
      MATERIAL_NAME:
        buy-price: 10.00         # price to buy 1x from server
        sell-price: 2.50         # price server pays for 1x (optional — uses multiplier if omitted)
        buy-enabled: true        # per-item override (optional)
        sell-enabled: true       # per-item override (optional)

• Set buy-price: -1 to disable buying a specific item.
• Set sell-price: -1 (or sell-enabled: false) to disable selling a specific item.
• Items not listed in any category automatically appear in Misc with a default price of $10.00 buy / $2.50 sell.

Special-meta items

By default, items with special metadata (enchanted books, potions, tipped arrows) are excluded because they can't be meaningfully sold without meta matching. You can change this:

features:
  include-special-meta-items: false   # default

---

Configuration Reference

config.yml

language: en_US                        # Language (en_US, pt_PT)

economy:
  currency-format: "$#,##0.00"         # Java DecimalFormat pattern
  currency-symbol: "$"

pricing:
  global-sell-multiplier: 0.25         # Global buy→sell multiplier
  sell-tax-percent: 0.0                # Optional tax on sell proceeds
  category-sell-multipliers:           # Per-category overrides
    BLOCKS: 0.20

full-inventory-behavior: DROP          # DROP or CANCEL

gui:
  main-title: "&6&lServer Shop"
  filler-material: GRAY_STAINED_GLASS_PANE

features:
  enable-buying: true
  enable-selling: true
  sell-hand-button: true
  sell-inventory-button: true
  include-special-meta-items: false

logging:
  enabled: true
  file: transactions.db

---

Transaction Logging

When logging.enabled: true (default), every buy and sell is recorded in an SQLite database at plugins/ServerShop/transactions.db.

Schema:

CREATE TABLE transactions (
    id         INTEGER PRIMARY KEY AUTOINCREMENT,
    uuid       TEXT,
    player     TEXT,
    type       TEXT,     -- 'BUY' or 'SELL'
    material   TEXT,
    amount     INTEGER,
    unit_price REAL,
    total      REAL,
    timestamp  INTEGER   -- Unix epoch seconds
);

You can query this with any SQLite client or DB browser to generate sales reports.

---

Known Limitations

• No admin GUI for viewing transaction stats (planned for v2).
• Search functionality is not implemented in v1 (planned for v2).
• Items with special meta (potions, enchanted books) are excluded by default; when enabled, only the base type is priced (no meta matching).
• The sell-inventory button sells all sellable items in the inventory at once — use with caution.
• Quantities are capped to 64 × inventory size; extremely large transactions may be slow.

---

Building from Source

cd servershop
mvn clean package

The shaded JAR will be in servershop/target/servershop-1.0.0.jar.

---

License

MIT — see the root LICENSE file.