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](../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.