qShadowTrader

Main Features

Random trader spawn near a valid player.
Configurable spawn intervals, chance, and distance.
Spawn restrictions by world (blocked-worlds) and optional allow-list (allowed-worlds).
Configurable offers in trades.yml:
- regular items (material, amount),
- custom items (item.*: name/lore/model-data/enchantments/flags/unbreakable).
Global purchase limits per offer (limit) displayed in lore.
Command execution on purchase ([console] / [player]).
Double-click purchase protection.
Chat notifications for trader spawn/despawn.
Player cooldown persistence in data.yml.

Trader Lifecycle

The plugin waits a random interval between spawn.interval-min and spawn.interval-max.
On each cycle, it rolls spawn.chance.
A random valid player is selected:
- online and alive,
- not in creative/spectator,
- world is not in spawn.blocked-worlds,
- if allowed-worlds is set, world must be in that list,
- player-cooldown must be satisfied.
Trader spawns at a safe location near that player (spawn-distance).
Offers are generated from trades.yml using weighted chance values.
Trader despawns after lifetime or when all active offers are bought out (if despawn-when-empty: true).

Commands

/shadowtrader spawn — spawn near self (if executed by player) or random valid target (from console).
/shadowtrader spawn random — force random spawn using valid target rules.
/shadowtrader spawn <player> — spawn near a specific player (with all validations).
/shadowtrader despawn — remove current active trader.
/shadowtrader reload — reload plugin configs.
/shadowtrader info — show trader status.
Alias: /st

Permissions

qshadowtrader.use
qshadowtrader.admin
qshadowtrader.spawn
qshadowtrader.reload

Configuration (`config.yml`)

Key sections:

spawn — auto-spawn logic (intervals, chance, worlds).
player-cooldown — cooldown before same player can be selected again.
spawn-distance — min/max distance from target player.
messages — chat messages.
lifetime — trader lifetime in seconds.
despawn-when-empty — despawn when all offers are exhausted.
trader — entity behavior/options.
menu — GUI settings.
protection.double-click-window-ms — anti-double-click window.

Offers (`trades.yml`)

Each offer is defined under items.<id> and supports:

material / amount (short format), or
item.* (advanced custom item format),
limit — max purchases for the current trader session,
chance — generation weight,
lore — offer description shown in GUI,
commands — commands to run on purchase.

Offer Lore Placeholders

%CURR_LIMIT% — current purchased amount
%MAX_LIMIT% — max limit for this offer

Command Prefixes

[console] command — execute as console
[player] command — execute as player
no prefix — executes as console

Supported placeholders in commands: <player>, %player%

Offer Example

totem:
  material: TOTEM_OF_UNDYING
  amount: 1
  limit: 1
  chance: 10
  lore:
    - ""
    - "&7Price: &62500"
    - "&7Limit: %CURR_LIMIT%/%MAX_LIMIT%"
    - ""
  commands:
    - "[console] eco remove <player> 2500"

Notes

Trader is protected from damage/combustion.
Offer limits reset on each new trader spawn.
If auto-spawn does not work, check spawn.enabled, world filters (allowed/blocked), and whether there are valid online players.

qShadowTrader

Main Features

Trader Lifecycle

Commands

Permissions

Configuration (config.yml)

Offers (trades.yml)

Offer Lore Placeholders

Command Prefixes

Offer Example

Notes

Configuration (`config.yml`)

Offers (`trades.yml`)