RoyalBazaar

# RoyalBazaar

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

A Hypixel-style Bazaar for Paper: a commodity market with algorithmic dynamic pricing, built for the eco suite.

Where (https://github.com/joogiebear/RoyalAuctions) handles one-off items, the Bazaar handles the things players trade constantly — cobblestone, wheat, mob drops, enchanted materials. Different problem, different UI.

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

## Contents

• (#why-not-an-order-book)
• (#the-pricing-model)
• (#requirements)
• (#install)
• (#commands--permissions)
• (#items-and-pricing-config)
• (#ecoshop-anchoring)
• (#menus)
• (#storage)
• (#integrations)
• (#building)
• (#gotchas)

## Why not an order book

Real Hypixel's bazaar is an order book — players place buy and sell orders and trade against each other. That needs liquidity. Hypixel has tens of thousands of concurrent players; your server almost certainly doesn't. On a normal server an order book is a ghost town: nobody to trade against, so nothing fills, and the feature is dead on arrival.

RoyalBazaar instead makes the server the counterparty, always, with infinite depth. There is always a price to buy at and a price to sell at, whether 200 players are online or 2. The prices still move with supply and demand — that's what the engine below is for.

## The pricing model

Each item has a mid price. Buying pushes it up, selling pushes it down, along an exponential curve:

``` mid' = mid × e^(±q / E) ```

The crucial part: cost and proceeds are the integral along that curve, not `quantity × price`:

``` buy cost = E × mid × (e^( q/E) − 1) × (1 + spread/2) sell proceeds = E × mid × (1 − e^(−q/E)) × (1 − spread/2) ```

Which gives three properties that matter:

• Small trades feel normal. When `q ≪ E`, `e^(q/E) ≈ 1 + q/E`, so cost ≈ `q × price`. Linear,
• unsurprising.
• Whales price themselves out. Dumping 100k of an item craters the price on yourself — each
• marginal unit sells for less than the last. You cannot drain the market at a flat price.
• No arbitrage loop exists. A round trip loses to the spread and to your own market impact:
• you buy (pushing the price up against yourself), then sell (pushing it back down). This isn't a
• rule patched on top to stop exploiters — the maths makes it impossible.

`elasticity` (E) is the knob that matters most per item: high = stable staple (cobblestone), low = volatile rare (netherite).

Mean reversion pulls each price back toward its `base_price` every tick, in log space, so a panic sell recovers over time instead of staying crashed:

``` mid = clamp( mid × e^((ln(base) − ln(mid)) × reversion_rate), floor, ceiling ) ```

Floor and ceiling caps are a hard backstop — clamped after every trade and every tick, so no formula edge case can send a price to 0 or ∞.

### A worked example

`base = 100`, `E = 50,000`, `spread = 5%`:

| Trade | Cost | New mid | |---|---|---| | Buy 64 | ~$6,565 | 100. 13 — barely moves ✅ normal play | | Buy 100,000 | ~$32. 7M | 739 — the curve punishes the whale ✅ |

## 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 (for `ecoitems:` items), EcoShop (for price anchoring), EconGuard, PlaceholderAPI |

Runs without the eco suite — you just lose custom items and EcoShop anchoring.

1. Drop `RoyalBazaar.jar` into `plugins/`. 2. Start the server. Configs generate on first run. 3. `/bz`.

## Commands & permissions

Base command `/bazaar`, aliases `/bz`, `/rbazaar`.

| Command | | |---|---| | `/bz` | Open the bazaar | | `/bz price ` | Show an item's live buy / sell / mid | | `/bz reload` | Admin. Reload config, categories, menus |

| Node | Default | |---|---| | `royalbazaar.use` | `true` | | `royalbazaar.admin` | `op` |

## Items and pricing config

The bundled `categories/` are vanilla-only — 338 items across farming, mining, combat, woods & fishes and oddities — so a fresh install works on any server without EcoItems. `oddities.yml` carries a commented EcoItems example showing `base_price: auto` and the NPC anchors; uncomment it only if that plugin is installed.

One file per category in `categories/`. The