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.