# 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-.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.