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.

---

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 and in the lore blocks: %price%, %base-price%, %discount%, %currency%, %balance%, %bulk%, %bulk-price%, %stock%, %stock-max%, %bought%, %limit%, %allowance%, %time-left%, %rotation%.

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, title and sound, all individually toggleable under announcements.

---

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.