copilot-swe-agent[bot]
072e7e294c
Co-authored-by: henriquescrrrr <192057244+henriquescrrrr@users.noreply.github.com>
235 lines
7.1 KiB
Markdown
235 lines
7.1 KiB
Markdown
# 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.
|