Add ServerShop plugin: complete Maven project with GUI, pricing, economy, i18n

Co-authored-by: henriquescrrrr <192057244+henriquescrrrr@users.noreply.github.com>
2026-02-22 11:02:24 +00:00
parent b6c1acb547
commit 06a4d1df48
28 changed files with 4398 additions and 0 deletions
@@ -0,0 +1,166 @@
+# 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](../README.md) 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
+
+```yaml
+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
+
+```yaml
+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
+
+```bash
+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](../LICENSE) for details.