Black Market

Black Market

A rotating, limited-stock shop. Every rotation the market draws a handful of items from a pool you define, optionally discounts them, and caps how many each player — and the server as a whole — may buy before the stock runs out.

Unlike the Shop addon (a fixed catalogue at fixed prices), the Black Market is built around scarcity: limited stock, rotating selection, random discounts, and optional opening windows.

Addon — drop X-Prison-BlackMarket-<version>.jar into plugins/X-Prison/addons/ and restart. Requires the Currency module to be enabled.

---

Files

File	Purpose
plugins/X-Prison/addons/BlackMarket/blackmarket.yml	All settings, GUI layout and messages
plugins/X-Prison/addons/BlackMarket/items/*.yml	One file per item in the pool
plugins/X-Prison/addons/BlackMarket/state.yml	Live stock and purchase counters (managed automatically)

state.yml is written by the plugin — do not edit it by hand. It is what makes stock, discounts and purchase limits survive a restart, so players cannot reroll the market by waiting for a reboot.

---

Availability modes

Set schedule.mode to one of:

ALWAYS_OPEN

The market can always be opened; only the stock rotates.

schedule:
  mode: ALWAYS_OPEN
  always-open:
    rotate-every: 6h

SCHEDULED

The market is closed except during defined windows. Running /blackmarket while closed shows a countdown to the next opening.

schedule:
  mode: SCHEDULED
  timezone: ''                      # empty = server default
  scheduled:
    open-at: [ '12:00', '18:00', '22:00' ]   # fixed daily times (HH:mm)
    every: 6h                                # used only when open-at is empty
    duration: 30m                            # how long it stays open
    rotate-on-open: true                     # fresh stock each opening

Durations accept 30s, 45m, 6h, 1d, or combinations such as 1d12h30m. A plain number is read as seconds.

---

Limits

Three independent caps. Any value <= 0 means "no limit". Items may override each of them.

limits:
  default-stock: 10                        # server-wide units per rotation
  default-per-player-per-rotation: 2       # resets every rotation
  default-per-player-lifetime: 0           # never resets
  bypass-permission: 'xprison.blackmarket.bypass.limit'

The bypass permission waives the personal limits only. Global stock is a shared resource and is never bypassed — otherwise one player could empty the market for everyone.

---

Discounts

Rolled once per item per rotation, so every player sees the same price and it survives a restart.

discounts:
  enabled: true
  chance: 0.35              # probability any stocked item is discounted
  tiers:
    - { percent: 10, weight: 50 }
    - { percent: 25, weight: 30 }
    - { percent: 50, weight: 15 }
    - { percent: 75, weight: 5 }

Set discountable: false on an item to exclude it.

---

The default item pool

The bundled pool sells real X-Prison content, not filler items — install it and it is ready to use. Each file names the module it needs at the top; if you do not run that module, delete the file or set enabled: false in it and the market simply skips it.

Item	Gives	Needs	Rarity
Token Cache	250,000 tokens (bought with money)	Currency	Common
Mine Bombs	3x normal bombs	Bombs	Common
Rigged Scales	2x money multiplier, 1h	Multipliers	Common
Auto Miner Cache	2 hours of Auto Miner	Auto Miner	Common
Forged Paperwork	2,500 Battle Pass XP	Battle Pass	Uncommon
Gem Pouch	500 gems	Currency	Uncommon
Skimmed Ledger	1.5x token multiplier, 2h	Multipliers	Uncommon
Mega Charge	1x mega bomb	Bombs	Uncommon
Inside Contact	2x Battle Pass XP booster, 2h	Battle Pass	Rare
Smuggled Pickaxe	A fresh starter pickaxe (3 per player, ever)	Enchants	Rare
Server Payday	2x money for the entire server, 30m	Multipliers	Legendary

Server Payday is the flagship: one player pays, everyone benefits. It has a stock of 1, a lifetime cap of 2, and a weight of 2, so it should surface rarely and feel like a server event. It also broadcasts who funded it.

Prices assume a mid-to-large economy. To rescale, multiply every price by the same factor rather than tuning items individually — the pool is balanced relative to itself.

---

Defining an item

Each file in items/ is one pool entry. The file name is the item id unless id is set.

id: contraband-crate
enabled: true
weight: 20                  # relative chance of being drawn; higher = more common

price: 750000               # any registered currency
currency: tokens            # omit to use default-currency

discountable: true
bulk-buy-amount: 1          # amount bought per shift-click

stock: 8                    # overrides the limits defaults
limit-per-rotation: 2
limit-lifetime: 0

permission: ''              # optional gate

display:
  material: CHEST           # vanilla, or nexo:id / oraxen:id / namespace:id
  glow: true
  name: "<gradient:#f7971e:#ffd200><bold>Contraband Crate</bold></gradient>"
  lore:
    - "<gray>A sealed crate, no questions asked."
    - ""
    - "%price-block%"
    - "%stock-block%"
    - "%limit-block%"
    - "%status-block%"

give-items:                 # items handed to the player
  crate:
    material: CHEST
    amount: 1

commands:                   # run from console
  - 'tokens give %player% 250000'

Command placeholders: %player%, %amount%, %item%.

Lore blocks

The four %…-block% markers expand into whichever list applies, so a single item definition renders correctly in every state. The lists live under gui.lore-blocks:

Marker	Expands to
%price-block%	price or price-discounted
%stock-block%	stock or stock-unlimited
%limit-block%	limit or limit-unlimited
%status-block%	status-buy, status-sold-out, status-limit-reached or status-no-permission

Item placeholders usable in display.name / display.lore, in the lore blocks, and on the confirmation menu's buttons: %price% / %unit-price%, %total-price%, %base-price%, %discount%, %currency%, %balance%, %amount%, %bulk%, %bulk-price%, %stock%, %stock-max%, %bought%, %limit%, %allowance%, %time-left%, %rotation%.

%price% is the per-unit price; %total-price% accounts for the quantity being bought, which is what you normally want on the confirm button.

Sold-out and limit-reached entries swap to the icons configured under gui.states, so scarcity stays visible instead of items vanishing from the menu.

---

Commands

Command	Permission	Description
/blackmarket	command.permission (optional)	Open the market
/blackmarket reload	xprison.blackmarket.admin	Reload config and item pool
/blackmarket rotate	xprison.blackmarket.admin	Force a restock
/blackmarket open	xprison.blackmarket.admin	Force open (SCHEDULED mode only)
/blackmarket close	xprison.blackmarket.admin	Force closed (SCHEDULED mode only)
/blackmarket resetlimits <player>	xprison.blackmarket.admin	Clear a player's purchase counters

Aliases default to /bm and /market, and are configurable. A forced open/close is released automatically at the next natural schedule boundary.

reload deliberately keeps the current rotation — it cannot be used to reroll stock.

---

Permissions

Node	Purpose
xprison.blackmarket.admin	Admin subcommands
xprison.blackmarket.bypass.limit	Ignore per-player purchase limits

---

PlaceholderAPI

Placeholder	Returns
%xprisonblackmarket_open%	true / false
%xprisonblackmarket_timeleft%	Time until restock (or close)
%xprisonblackmarket_next_open%	Time until next opening (SCHEDULED mode)
%xprisonblackmarket_rotation%	Current rotation number
%xprisonblackmarket_slots%	How many items are stocked
%xprisonblackmarket_slot_<n>_id|name|price|discount|stock%	Details of the n-th stocked item (1-indexed)
%xprisonblackmarket_<item>_stock%	Stock left for that item
%xprisonblackmarket_<item>_bought%	How many the player has bought lifetime
%xprisonblackmarket_<item>_discount%	Discount percent on that item

---

Boss bar and announcements

A countdown boss bar shows time until restock (or close), and optionally counts down to the next opening while closed.

Market open, market close and restock each have their own broadcast, on-screen title and sound, all individually toggleable under announcements:

announcements:
  rotation:
    enabled: true
    broadcast: "<light_purple>The Black Market restocked."
    title:
      enabled: true
      title: "<gradient:#8e2de2:#4a00e0><bold>BLACK MARKET</bold></gradient>"
      subtitle: "<gray>Fresh stock — <white>/%command%"
      fade-in: 1      # seconds
      stay: 3
      fade-out: 1
    sound:
      enabled: true
      sound: BLOCK_NOTE_BLOCK_PLING
      volume: 0.7
      pitch: 1.4

In ALWAYS_OPEN mode the rotation announcement is the one that fires on each restock; in SCHEDULED mode you also get market-open and market-close. Set enabled: false on any block (or on its title / sound child) to silence just that part.

---

Notes

• All strings are MiniMessage; legacy & codes also work.
• Prices are handled with exact decimal arithmetic, so OP-scale values stay precise.
• The market never charges a player who cannot fit the items — inventory space is checked first.
• State is single-server. Running several servers off one folder is not supported.