qShadowTrader

Support me on Ko-fi

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

1. The plugin waits a random interval between `spawn.interval-min` and `spawn.interval-max`. 2. On each cycle, it rolls `spawn.chance`. 3. 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. 4. Trader spawns at a safe location near that player (`spawn-distance`). 5. Offers are generated from `trades.yml` using weighted `chance` values. 6. 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.