PlayerAuctions

PlayerAuctions

PlayerAuctions is a modern and feature-rich auction house plugin for PaperMC servers. It provides a robust, intuitive, and scalable platform for players to buy and sell items, fully integrated with Vault-based economies and PlaceholderAPI.

✨ Overview

PlayerAuctions provides a robust, intuitive, and scalable platform for players to buy and sell items securely. Fully integrated with Vault-based economies and the latest Paper 1.21 API, PlayerAuctions brings a premium marketplace experience to your server.

Strictly Paper 1.21 - Strictly Paper 1.21: Canceled auctions and sold item revenues are securely routed to the player's personal mailbox, solving inventory management issues! - Strictly Paper 1.21: Extremely reliable, zero-latency commands with intelligent Tab Completions. - Strictly Paper 1.21: 100% native MiniMessage GUI item formatting including Hex, Gradients, and auto-italic removal. - Strictly Paper 1.21: Dropped legacy version support for maximum performance and zero bloat.

🚀 Core Features

📬 Mailbox System (NEW)

No more dropped items when a player's inventory is full! - Expiration Protection: Canceling an active auction routes the item safely into the Mailbox. - Expiration Protection: Sold items send a "Revenue Notification" to the seller's Mailbox. Claiming it deposits the Vault money—acting as a satisfying transaction receipt. - Expiration Protection: Items automatically expire after a configurable duration (default: 30 days).

📢 Global Broadcast Notifications

- Keep the economy active! Broadcasts when items are listed and bought. - Configurable Range: Click "View Auction" right in chat. - Configurable Range: Broadcast to GLOBAL, WORLD, or NONE.

🎨 Premium GUI Interface

- Search Engine: Fully supports Hex RGB colors and gradients for borders, titles, and formats. - Search Engine: Quickly jump between categories like Blocks, Tools, Weapons, etc. - Search Engine: Sort auctions by Price (Ascending/Descending), Time Left, and Newest. - Search Engine: In-game robust search to filter active items.

🛡️ Secure Transactions

- Persistent JSON Storage: Prevents duplicate purchase exploits (race conditions) using optimistic database locking. - Persistent JSON Storage: Lightweight, concurrent-safe flat-file storage with auto-backups on writes.

---

⌨️ Commands & Permissions

> Command Aliases: `/ah`, `/auction`, `/auctionhouse`

| Command | Description | Permission | Default | |---|---|---|---| | `/ah` | Opens the main Auction House GUI | `playerauctions.use` | `true` | | `/ah sell <price> [buy_now] [time]` | List the item in your hand on the AH | `playerauctions.sell` | `true` | | `/ah myauctions` | View and manage your current listings | `playerauctions.use` | `true` | | `/ah mailbox` | Open your Mailbox to claim money and items | `playerauctions.use` | `true` | | `/ah search <keyword>` | Search for a specific item | `playerauctions.search` | `true` | | `/ah categories` | Browse items by predefined categories | `playerauctions.categories` | `true` | | `/ah history [player]` | View your (or others') transaction history | `playerauctions.history(.others)` | `true` (`op`) | | `/ah notify <on/off>` | Toggle personal auction notifications | `playerauctions.notify` | `true` | | `/ah reload` | Reload configuration files | `playerauctions.reload` | `op` |

Admin Permissions - `playerauctions.admin` - Grants all administrative commands and bypasses.

---

🔧 Configuration Guide

PlayerAuctions is highly modular. Check your `config.yml` to customize the experience:

```yaml auction: max-auctions-per-player: 5 tax-percentage: 5.0 # Removes 5% from all successful sales

broadcast: enabled: true on-listing: true on-purchase: true range: GLOBAL # GLOBAL, WORLD, NONE

mailbox: enabled: true retention-days: 30 # Days before Mailbox items auto-expire ```

💬 Placeholders (PlaceholderAPI)

Integrate statistics into your scoreboard or tablist! - `%playerauctions_total_auctions%` - Tracks globally active auctions. - `%playerauctions_player_listings%` - Tracks the viewer's active listing count.

---

📦 Installation

1. Ensure your server is running Vault. 2. Install Vault and an economy provider (e.g., EssentialsX). 3. Drop `PlayerAuctions-3.1.0.jar` into your `plugins/` folder. 4. Restart the server. 5. *(Optional)* Modify `config.yml` and `messages.yml` using standard `<color>` MiniMessage syntax!

🤝 Support & Issues

Developed by MinekartaStudio. Found a bug or need support? Please reach out via our GitHub repository issues tab or our Discord server.