Add ServerShop plugin - complete implementation

Co-authored-by: henriquescrrrr <192057244+henriquescrrrr@users.noreply.github.com>
2026-02-22 11:02:34 +00:00
parent 3a708c054c
commit 072e7e294c
25 changed files with 3472 additions and 0 deletions
@@ -0,0 +1,234 @@
+# 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](../README.md) 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](https://www.spigotmc.org/resources/vault.34315/) 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`:
+```yaml
+pricing:
+  global-sell-multiplier: 0.25   # Server pays 25% of buy price (75% spread)
+```
+
+Per-category overrides:
+```yaml
+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`:
+```yaml
+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
+
+```yaml
+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:
+
+```yaml
+features:
+  include-special-meta-items: false   # default
+```
+
+---
+
+## Configuration Reference
+
+### `config.yml`
+
+```yaml
+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:
+```sql
+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 planned but not implemented in v1 (click Search shows a placeholder message).
+- 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
+
+```bash
+cd servershop
+mvn clean package
+```
+
+The shaded JAR will be in `servershop/target/servershop-1.0.0.jar`.
+
+---
+
+## License
+
+MIT — see the root [LICENSE](../LICENSE) file.