RoyalAuctions

# RoyalAuctions

RoyalPlugins: (https://discord.gg/D3HRBJXsHj) · (https://github.com/joogiebear/RoyalAuctions/wiki) · (https://github.com/joogiebear/RoyalAuctions/issues) · (https://github.com/joogiebear/RoyalAuctions)

A Hypixel-style Auction House for Paper, built to work properly with the eco suite (EcoItems, EcoArmor, Talismans, Reforges, EcoPets, EcoScrolls, StatTrackers) — and to work just as well on a server that has none of them.

Part of a suite with (https://github.com/joogiebear/RoyalBank), (https://github.com/joogiebear/RoyalBazaar) and (https://github.com/joogiebear/EconGuard).

## Contents

• (#requirements)
• (#install)
• (#commands)
• (#permissions)
• (#menus)
• (#categories)
• (#item-tiers)
• (#confirmations)
• (#storage)
• (#placeholderapi)
• (#npcs-citizens)
• (#building)
• (#gotchas)

## Requirements

| | | |---|---| | Server | Paper 26. 2 or newer (Java 25) | | Required | Vault and an economy provider (EssentialsX, CMI, an EcoBits currency with `vault: true`, …) | | Optional | eco suite, PlaceholderAPI, EconGuard, Citizens |

The eco suite is entirely optional. Without it you lose custom-item categorisation and the tier filter; everything else works, and the plugin never touches an eco class.

1. Drop `RoyalAuctions.jar` into `plugins/`. 2. Start the server. Configs generate on first run. 3. `/ah` — done.

JDBC drivers and HikariCP are downloaded at runtime by Paper's library loader; nothing is shaded.

## Commands

Base command `/auctionhouse`, aliases `/ah`, `/auctions`, `/auction`.

| Command | What it does | |---|---| | `/ah` | Open the hub — Auction Browser, View Bids, Manage Auctions | | `/ah browse` | Straight to the browser | | `/ah bids` | Auctions you have bid on ("top bidder on X of Y") | | `/ah sell` (or `create`) | Create-auction flow | | `/ah search ` | Search listings by name | | `/ah listings` | Manage your own listings | | `/ah collect` | Claim purchases and returned items | | `/ah ` | View that player's active auctions | | `/ah category` | Admin. Inspect the held item: category, which rule matched, and tier | | `/ah reload` | Admin. Reload config, categories, menus, rarities |

## Permissions

| Node | Default | | |---|---|---| | `royalauctions.use` | `true` | Open and browse | | `royalauctions.sell` | `true` | List items | | `royalauctions.admin` | `op` | `/ah reload`, `/ah category` |

> NPCs run commands as the clicking player, so they inherit that player's permissions. If you > restrict `royalauctions.use`, a player without it clicking the NPC gets nothing — that's expected.

Every screen is a file in `gui/`, authored in the EcoMenus dialect — the same shape you already know from EcoMenus/EcoShop.

```yaml title: "&8Auction Browser" rows: 6

mask: items: - red_stained_glass_pane # 1 - black_stained_glass_pane # 2 pattern: - "A10000000" # digits = mask.items filler - "A20000000" # 0 / letters = named dynamic regions - "A67777777"

regions: category-slots: "A" # column 1: the category buttons content-slots: "0" # the listing grid

slots: - id: sort item: 'hopper name:"&eSort: &f%sort%"' lore: - "&7Click to change sorting." location: # 1-based row/column, not raw slot indexes row: 6 column: 6 left-click: - id: ah_sort ```

Files: `hub`, `browse`, `bids`, `seller`, `manage`, `collection`, `create`, `duration`, `bid`, `confirm-purchase`, `confirm-auction`, `confirm-bid`, `confirm-cancel`.

Two extensions over stock EcoMenus:

• Named mask regions — one menu can have several dynamic areas (`content-slots` and
• `category-slots`), not just one.
• Per-click actions — `left-click:` and `right-click:` can do different things. A button with
• no `right-click:` behaves the same on both, so nothing changes for buttons that don't care.

List placeholders. A lore line that is exactly `%tier_list%` (or `%type_list%`) expands into one line per option, with the current one marked — that's how the filter buttons show their whole list rather than just the current value:

```yaml - id: tier item: 'nether_star hide_attributes name:"&eItem Tier"' lore: - "&7Filter listings by item tier." - "" - "%tier_list%" # -> "> EPIC" for current, dimmed for the rest - "" - "&eLeft-click &7to go up" - "&eRight-click &7to go down" left-click: - id: ah_tier_prev right-click: - id: ah_tier_next # swap these two to revers