CommunityMarket/ServerShop/README.md

ServerShop

A professional server-run global market plugin for Paper/Purpur 1.21.1 servers. This plugin provides a GUI-driven shop where players can buy and sell all game items at configurable prices.

Overview

ServerShop is designed to work alongside the CommunityMarket player-to-player marketplace. It features a large spread between buy and sell prices, ensuring that player-to-player trading via CommunityMarket remains the preferred option for best deals.

How the Spread Works

• Buy Price: What the server charges when selling to players (higher)
• Sell Price: What the server pays when buying from players (lower)
• Default Spread: 75% (sellMultiplier = 0.25)

For example, a Diamond with a buy price of $100:

• Server sells to player: $100
• Server buys from player: $25 (100 × 0.25)
• Players trading via CommunityMarket might sell for $60-80, making it better for both buyer and seller

Features

• GUI-Only Interface: All interactions through intuitive inventory GUIs
• Category System: Items organized into 10 categories (Blocks, Ores, Farming, Food, Mob Drops, Redstone, Decoration, Tools, Combat, Brewing, Misc)
• Search: Find items by name via chat input
• Pagination: Browse large categories with page navigation
• Quantity Selection: Adjust amounts with -32/-16/-8/-1/+1/+8/+16/+32 and MIN/MAX buttons
• Sell Hand / Sell Inventory: Quick-sell shortcuts from the main menu
• Vault Economy: Full integration with any Vault-compatible economy plugin
• Multi-Language: English (en_US) and Portuguese (pt_PT) included
• Transaction Logging: SQLite database for tracking all transactions
• Anti-Exploit: Comprehensive protection against item duplication and GUI exploits
• Configurable Pricing: Per-category multipliers, per-item overrides, buy/sell toggles

Requirements

• Paper or Purpur 1.21.1+
• Java 21
• Vault + an economy provider (e.g., EssentialsX, CMI)

Installation

1. Download the ServerShop-1.0.0.jar
2. Place it in your server's plugins/ folder
3. Make sure Vault and an economy plugin are installed
4. Start/restart the server
5. Edit configuration files in plugins/ServerShop/

Commands

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

Permissions

Permission	Description	Default
servershop.use	Access the server shop	true
servershop.buy	Buy items from the shop	true
servershop.sell	Sell items to the shop	true
servershop.sell.hand	Use the "sell hand" feature	true
servershop.sell.inventory	Use the "sell inventory" feature	true
servershop.admin	Admin permissions	op
servershop.admin.reload	Reload configuration	op

Configuration

config.yml

Main plugin settings including:

• Language selection
• Economy settings (symbol, decimal places, sell tax)
• Pricing defaults (global sell multiplier)
• Shop behavior (full inventory action, sell hand/inventory toggles)
• GUI settings (titles, filler items, sounds)
• Transaction logging

prices.yml

Item pricing configuration with:

• Categories: Define categories with icon, sell multiplier, and item lists
• Items: Each item has a buy price; sell price is auto-calculated
• Overrides: Per-item buy/sell price overrides and enable/disable toggles

Adding/Editing Prices

categories:
  MyCategory:
    icon: DIAMOND         # Category icon material
    sell-multiplier: 0.30 # Override global multiplier
    buy-enabled: true
    sell-enabled: true
    items:
      DIAMOND: 100.0      # Buy price = $100, Sell = $100 * 0.30 = $30
      EMERALD: 50.0       # Buy price = $50, Sell = $50 * 0.30 = $15

Per-Item Overrides

overrides:
  ELYTRA:
    sell: 500.0           # Override auto-calculated sell price
  COMMAND_BLOCK:
    buy-enabled: false    # Cannot be purchased
    sell-enabled: false   # Cannot be sold

Language Files

Located in lang/en_US.yml and lang/pt_PT.yml. All GUI labels and messages are fully customizable.

Building from Source

cd ServerShop
mvn clean package

The compiled JAR will be in ServerShop/target/.

Architecture

pt.henrique.servershop
├── ServerShop.java          # Main plugin class
├── command/
│   └── ShopCommand.java     # /shop command handler
├── config/
│   ├── ConfigManager.java   # Main config (config.yml)
│   └── MessageManager.java  # Language/message system
├── economy/
│   └── EconomyManager.java  # Vault economy integration
├── pricing/
│   ├── PricingService.java  # Price calculation & lookup
│   └── ItemPrice.java       # Price data model
├── category/
│   ├── CategoryRegistry.java # Category management
│   └── ShopCategory.java    # Category data model
├── gui/
│   ├── ShopGui.java         # GUI interface
│   ├── GuiManager.java      # GUI orchestration
│   ├── MainShopGui.java     # Main menu
│   ├── CategoryGui.java     # Category browser
│   ├── ItemDetailGui.java   # Buy/sell detail view
│   └── SearchResultsGui.java # Search results
├── service/
│   └── ShopService.java     # Buy/sell business logic
├── transaction/
│   └── TransactionLogger.java # SQLite transaction logging
├── listener/
│   └── GuiListener.java     # Anti-exploit GUI listener
└── util/
    ├── ItemBuilder.java     # Fluent ItemStack builder
    └── TextUtil.java        # Text formatting utilities

Known Limitations

• Special Items: Enchanted books, potions, and other items with special metadata are excluded by default (configurable via pricing.include-special-items)
• Dynamic Pricing: v1.0 uses static, config-driven pricing only. Dynamic supply/demand pricing may be added in a future version
• New Items: Items added in future Minecraft updates will automatically fall into the "Misc" category if not explicitly configured

License

MIT License - See LICENSE for details.