Плагин SoulAuction [2.2.0]

Описание плагина SoulAuction:​

​

Зачем админу SoulAuction:​

Сеть и анти-дюп (кратко) в SoulAuction:​

Что умеет SoulAuction:​

Платформа и сеть​

• Paper 1.21+ и Folia (folia-supported: true), region-aware потоки, без legacy-scheduler на hot path.
• Один JAR, зависимости через Paper libraries (не shade / fat-jar).
• Мульти-аукционы в одном плагине: auctions/<id>.yml, свои права, экономика, TTL, налоги, lore.
• Хранение лотов: JSON / YAML / SQLITE / MYSQL; HikariCP, async миграции схемы.
• Прокси-сеть: общая MySQL + Redis (локи покупки/продажи между серверами, pub/sub инвалидация кэша).
• Анти-дюп: in-process locks + Redis NX + атомарный UPDATE … WHERE status='ACTIVE'; откат при ошибке оплаты / полном инвентаре.
• Sell: escrow в GUI; /ah sell — strict-снятие предмета до записи в БД.
• /ah admin migrate — перенос данных между режимами хранения; миграция legacy layout и zAH V3.
• Проверка обновлений (async), bStats.

Экономика и лимиты​

• Валюты: VAULT, PLAYER_POINTS, EXPERIENCE, COINS_ENGINE, ITEM; несколько allowed-economies на аукцион.
• Per-auction знак валюты, позиция до/после числа, MiniMessage, PlaceholderAPI в символе.
• Налоги: FLAT / VAT / CAPITALISM; saleTaxPercent, buyTaxPercent; bypass и discount по правам.
• Глобальные и per-auction material-rules; custom-item-rules (ItemsAdder, Oraxen, MMOItems и др.).
• Tag-price: max-цена по NBT-тегам (глобально + tag-price-rules в аукционе).
• Лимиты лотов: soulauction.<auctionId>.<N>, soulauction.all.<N>; override per-player через admin.
• Slot rent: игрок платит и временно получает доп. слоты сверх лимита по правам; /ah rent, повторная покупка продлевает срок.
• Min/max цена: глобально, per-auction, per-player permission (soulauction.price.min/max.*).
• Cooldown на sell; blacklist продавцов; запрет миров; whitelist/blacklist материалов.
• Оффлайн-продавец: pending money claim; LuckPerms offline для налогов/лимитов.

Витрина и GUI игрока​

• Browser-GUI: категории, сортировки, пагинация, live TTL в lore (тик раз в секунду).
• Поиск: в чате (/ah search), fuzzy, regex (опционально), fix раскладки, мультиязычный индекс (ru,en).
• Фильтры: min/max цена, только избранные продавцы, только избранные лоты, фильтр по продавцу.
• Sell-GUI: ±1 количество, добор идентичных стаков из инвентаря (полная сериализация NBT), escrow до confirm.
• Подтверждение покупки; preview контейнеров (сундуки и т.п.).
• Hub (gui/hub.yml): избранное, мои лоты, claim, история, vault, rent, resell — live-счётчики в lore.
• Избранные продавцы / избранные лоты; последние сделки аукциона.
• Мои лоты: снятие, смена цены в GUI (→ Telegram reply при включённом notify).
• Claim просроченных/снятых; уведомление продавцу при expire (онлайн / при входе).
• Player vault: хранилище просроченных, /ah vault, expire → vault; забрать или перевыставить.
• Resell: /ah resell + hub (всё / vault / активные); cooldown, scope по текущему аукциону в hub.
• История покупок/продаж со снимком предмета в GUI (custom items).
• Per-auction listing-lore-template; filler material / CMD per-auction.
• WorldGuard trade regions: sell/buy/open только внутри указанных регионов (per-auction).

Рынок регионов (WorldGuard)​

• Продажа и покупка WG-регионов за валюту аукциона; отдельный GUI и команды (/ah regions, /regions, алиасы).
• Preview региона (spectator, cooldown); телепорт после покупки (auto / по кнопке).
• История покупок/продаж регионов; лимит лотов регионов на игрока.
• Перехват /rg sell|cancel|my|clear при установленном WorldGuard.

Автоматизация и «оживление»​

• Fake activity: синтетические лоты per-auction, пул ников/предметов, таймер, /ah admin fake, toggle в админ-GUI.
• Stock-bot (stock-bot/): серверный shop (бот продаёт, пополняет stock) + instant-buy (бот скупает лоты игроков); не fake activity.

Уведомления и трансляции​

• Announcements в чат сервера: 4 переключателя (покупка/листинг × предметы/регионы), фильтр min-price.
• Discord webhook, embed, аватарки игроков (Minotar/Crafatar).
• Telegram: listed / sold / expired; reply под постом при sold и смене цены; HTML parse mode.
• chat-routing: GLOBAL — один chat-id; PER_AUCTION — telegram-chat-id в auctions/*.yml (пусто = молчит).
• Async HTTP, шаблоны в lang/messages_*.yml, locale для notify.

Админка​

• /ah admin GUI: список аукционов, создать аукцион (wizard), настройки per-auction, toggle fake activity.
• Логи: по игроку, по id лота, audit, purge истории, recover claim.
• sellfor, fake, runtime blacklist, cache stats/rebuild/invalidate.
• parse tags|nbt — разбор предмета в руке (custom items).
• /ah view, /ah admin selling, GUI истории с иконками предметов.

Интеграции и прочее​

• PlaceholderAPI %soulauction_*%: счётчики лотов, claim, лимиты, статистика сделок (per-currency), сортировка/категория игрока.
• SkinsRestorer / Mojang — головы продавцов в избранном; общий скин для fake sellers.
• MiniMessage в lang: ru + en, multi-line сообщения в чат.
• Алиасы команд в config (ax, auction, …); /ah reload — конфиг + lang + GUI yml.
• Экспериментальные флаги per-auction: bids-enabled, rent-enabled (задел в конфиге).

Отображение цен (auctions/*.yml)​

# без ограничения (по умолчанию)
world-guard-trade-regions: []

# регионы в текущем мире игрока (/rg list — id региона)
world-guard-trade-regions:
  - shop
  - market

# конкретный мир + регион
world-guard-trade-regions:
  - world:mall
  - world_nether:trade_hub

Срок лотов (TTL) и claim​

• Пока лот ACTIVE, в витрине и в «Мои лоты» (если срок включён) в lore: осталось / до какого времени; в открытой витрине таймер обновляется раз в секунду.
• Истёк срок, никто не купил: лот снимается (EXPIRED), предмет один раз попадает в claim (claims.json), не в void.
• Продавец: в чат (онлайн сразу, оффлайн при входе) — что истекло и [Забрать в меню] → /ah expired [auctionId]; выдача предметов — /ah claim (меню просроченных только показывает, слоты не редактируются).
• Выставление: в чат несколько строк — товар, кол-во, цена, аукцион; отдельно блок про срок или «без срока» (success-listed, success-listed-expiry-timed / success-listed-expiry-unlimited в lang/messages_*.yml).
• На одном процессе: lock на listingId + при SQL переход ACTIVE → EXPIRED/SOLD/CANCELLED атомарный; claim снимается из буфера до выдачи в инвентарь.

• Текст: ₽, мон., алм.
• MiniMessage / glyph: <glyph:coin> (ItemsAdder, Nexo и аналоги — по доке ресурспака)
• PAPI (с currencySymbolPlaceholderApi: true): %img_economy%

Сообщения (plugins/SoulAuction/lang/)​

• prefix — префикс всех строк с {prefix}.
• Ключи — MiniMessage; {price} уже с форматом аукциона, в который смотрит игрок.
• Несколько строк в чате: ключ как YAML-список строк — плагин шлёт каждую строку отдельным сообщением (MessageService.send). Одна строка — как раньше. Поиск в чате, успех продажи, истечение лота, usage-команды — в этом формате.
• Плейсхолдеры lore лота в GUI: {seller}, {price}, {id}, {auction}, {expires_in}, {expires_at} (последние два — если TTL включён); опционально listingLoreTemplate в auctions/*.yml.

PlaceholderAPI для плагина SoulAuction:​

Счётчики​

Настройки игрока​

Статистика сделок​

Автофейки (fake activity)​

Включение per-auction​

Пул (plugins/SoulAuction/fake-activity/)​

settings.yml (главное)​

items.yml — поля записи​

• id — имя для себя
• material / amount — vanilla-стек (игнорируется, если задан item-base64)
• item-base64 — полный снимок предмета (NBT, custom items)
• min-price / max-price — 0 = из settings.yml
• auction-ids — пусто = любой аукцион; иначе только перечисленные
• weight — относительный шанс выбора (больше = чаще)

Ручной фейк​

Поведение​

• Фейки участвуют в сортировке, поиске, фильтрах как обычные лоты.
• Снять /ah cancel может только админ с soulauction.command.cancel.any (продавец — synthetic UUID).
• На прокси с MySQL+Redis фейки синхронизируются как обычные listing records.

Рынок регионов (WorldGuard)​

Требования​

• WorldGuard на сервере (softdepend).
• В config.yml → region-market.enabled: true, затем /ah reload (или рестарт).
• У продавца регион должен быть его (owner в WG); у покупателя — деньги на выбранном аукционе.

Включение (fresh install)​

region-market:
  enabled: true
  hide-world-name: true
  ah-subcommand-aliases: [rg]
  standalone-commands: [regions]
  allowed-auction-ids: []

Команды​

GUI​

Права (два слоя)​

Vault, resell, slot rent и hub​

Hub (личный кабинет)​

Player vault (хранилище)​

Resell (массовое перевыставление)​

Slot rent (аренда слотов)​

Tag-price (лимит по тегам предмета)​

Stock-bot (серверный бот)​

Скины продавцов (config.yml → seller-skins)​

source​

fallback-skin и fake-seller-skin​

seller-skins:
  source: skins-restorer
  fallback-skin: "DefaultHead"
  fake-seller-skin: "ServerLogo"

Цепочка lookup (SkinsRestorer)​

1. findOrCreateSkinData(ник) — или fake-seller-skin, если продавец synthetic и поле задано
2. findSkinData(fallback-skin) — если указан
3. getSkinForPlayer(uuid, nick) — SR defaultSkins из конфига SkinsRestorer

Прогрев при старте​

• если задан fake-seller-skin — прогревается он (+ fallback-skin, если указан);
• иначе — все ники из пула фейков + fallback-skin.

Админ-GUI​

Скины продавцов (config.yml → seller-skins)​

source​

fallback-skin и fake-seller-skin​

Цепочка lookup (SkinsRestorer)​

1. findOrCreateSkinData(ник) — или fake-seller-skin, если продавец synthetic и поле задано
2. findSkinData(fallback-skin) — если указан
3. getSkinForPlayer(uuid, nick) — SR defaultSkins из конфига SkinsRestorer

Прогрев при старте​

• если задан fake-seller-skin — прогревается он (+ fallback-skin, если указан);
• иначе — все ники из пула фейков + fallback-skin.

Команды плагина SoulAuction:​

Команды для игроков​

• /ah — открыть аукцион по умолчанию.
• /ah <auctionId> — открыть конкретный аукцион.
• /ah sell <price> — выставить предмет из руки в аукцион по умолчанию.
• /ah sell <auctionId> <price> — выставить в выбранный аукцион.
• /ah sell <price> <auctionId> — альтернативный порядок аргументов.
• /ah my [auctionId] — показать свои активные лоты.
• /ah selling [auctionId] — GUI активных лотов.
• /ah expired [auctionId] — GUI просроченных предметов (claim).
• /ah purchased [auctionId] — GUI истории покупок.
• /ah history [auctionId] — GUI истории продаж.
• /ah search <текст> — поиск: закрытие GUI, запрос в чате (кнопка отмены в сообщении); после ввода — обновлённая витрина и итог в чат.
• /ah search <auctionId> <текст> — то же в выбранном аукционе.
• /ah search cancel — отмена поиска и возврат в аукцион.
• /ah page <номер> [auctionId] — открыть нужную страницу аукциона.
• /ah claim [all] — забрать просроченные/снятые предметы.
• /ah vault — GUI хранилища просроченных предметов.
• /ah resell — массово перевыставить из vault и/или активных лотов.
• /ah rent — GUI аренды доп. слотов листинга.
• /ah cancel <id> — снять свой лот и вернуть предмет.
• Рынок регионов (WorldGuard): /ah regions, /ah rg, /regions — см. раздел «Рынок регионов».
• Алиасы команды настраиваются в config.yml через commandAliases (например ax, auction).

Команды для админов​

• /ah reload — перезагрузка конфигов и сообщений.
• /ah purge <days> — очистка истории сделок старше N дней.
• /ah admin history <player> [limit] — история игрока (в игре — GUI с иконками предметов; консоль — текст в чат).
• /ah admin logs [страница] — GUI логов: по игроку, по id лота, последние сделки, audit.
• /ah admin selling <player> [auctionId] — GUI активных лотов игрока.
• /ah admin blacklist add|remove <player> — runtime blacklist продажи.
• /ah admin recover <claimId> — выдать claim в инвентарь.
• /ah admin audit [limit] — последние audit-записи.
• /ah admin cache stats|rebuild|invalidate — кэш каталога.
• /ah admin sellfor <player> <auctionId> <price> — выставить лот от имени игрока (предмет в руке).
• /ah admin fake <ник> <auctionId> <цена> — synthetic-лот от указанного ника (предмет в руке; см. автофейки).
• /ah admin gui [страница] — GUI списка аукционов (кнопка «Логи и история»; ПКМ по аукциону — настройки).
• /ah admin parse tags|nbt — разбор NBT/тегов предмета в руке (custom items).
• /ah view <player> [auctionId] — GUI лотов игрока.

Права плагина SoulAuction​

Базовые​

• soulauction.command.ah — использовать /ah.
• soulauction.command.sell — использовать /ah sell.
• soulauction.command.reload — использовать /ah reload.
• soulauction.command.admin — админ-команды и purge.
• soulauction.priority.10 — выше приоритет в сортировке лотах (любое N).
• soulauction.command.my — использовать /ah my.
• soulauction.command.claim — использовать /ah claim.
• soulauction.command.vault — /ah vault.
• soulauction.command.resell — /ah resell.
• soulauction.command.rent — /ah rent.
• soulauction.command.cancel.any — снимать чужие лоты командой /ah cancel.

Рынок регионов (WorldGuard)​

• soulauction.command.regions — /ah regions, /regions и алиасы.
• soulauction.region.sell — выставить регион на продажу.
• soulauction.region.buy — купить регион на рынке.

Аукцион-специфичные (задаются в auctions/*.yml)​

• openPermission — право открыть этот аукцион.
• buyPermission — право покупать лоты в этом аукционе.
• sellPermission — право выставлять лоты в этот аукцион.

• soulauction.open.vip
• soulauction.buy.vip
• soulauction.sell.vip

Динамические лимиты лотов по правам​

• soulauction.<auctionId>.1 — лимит 1 активный лот в этом аукционе.
• soulauction.<auctionId>.5 — лимит 5 активных лотов в этом аукционе.
• soulauction.all.1 — общий лимит 1 на все аукционы.
• soulauction.all.5 — общий лимит 5 на все аукционы.

Налоги​

• soulauction.tax.bypass — без налога продажи и покупки.
• soulauction.tax.discount.<процент> — скидка на налог продажи (берётся максимальная).

Границы цены​

• Глобально: limits.minPrice, limits.maxPrice в config.yml.
• Per-auction: minPrice, maxPrice (0 = взять глобальные).
• Tag-price: config.yml → tag-price и auctions/<id>.yml → tag-price-rules — см. раздел «Tag-price».
• soulauction.price.min.<цена> — минимальная цена лота для игрока.
• soulauction.price.max.<цена> — максимальная цена лота для игрока.

Объявления на весь сервер (чат)​

announcements:
  items:
    broadcast-purchase: true
    broadcast-listing: true
    min-purchase-price: 5000
    min-listing-price: 0
  regions:
    broadcast-purchase: true
    broadcast-listing: false
    min-purchase-price: 10000
    min-listing-price: 0

Discord и Telegram​

• Discord: notifications.discord.enabled, webhookUrl (Incoming Webhook канала Discord).
• События: notify-sold, notify-listed, notify-expired, фильтр min-price.
• notifications.locale— язык шаблонов (ru, en, …); тексты в lang/messages_*.yml:
  • notify-telegram-listed, notify-telegram-sold, notify-telegram-expired
  • notify-telegram-reply-sold, notify-telegram-reply-price — reply под постом лота
  • notify-discord-title-, notify-discord-field-
• Плейсхолдеры: {auction} — display-name из auctions/<id>.yml (не internal id), {auction_id} — id файла (global), {seller}, {buyer}, {price} (с валютой), {item} (название из lang Minecraft по notifications.locale), {amount}, {id}, {region}, {world}.
• Telegram HTML: notifications.telegram.parse-mode: HTML (дефолт). В шаблонах — <b>, <i>, <code>. Пустая строка: " " в YAML-списке. Редактируй lang/messages_*.yml → /ah reload.
• Отправка асинхронная (Java HTTP), без бота на сервере Minecraft.
• Аватарки в Discord: notifications.discord.show-player-avatars. CDN: avatar-provider = MINOTAR или CRAFATAR.

Telegram — пошагово​

1. Создай канал.
2. Добавь бота администратором с правом публиковать сообщения.

• chat-id: "@имя_канала" — только @…, без Telegram – a new era of messaging
• или числовой id -100… (см. ниже)

• @имяне работает — только числовой id
• Опубликуй в канале пост после того, как бот стал админом (хоть «test»)
• Открой https://api.telegram.org/bot<token>/getUpdates → "chat":{"id":-1001234567890,"type":"channel"}
• chat-id: "-1001234567890" — с минусом, в кавычках
• Пустой result → обнови страницу после поста; forward боту id канала не даёт
• Лайфхак: временно сделай канал публичным → возьми id → снова приватный (id не меняется)

1. Создай группу, добавь бота.
2. Напиши в группе любое сообщение.
3. getUpdates → chat.id (обычно -100…) → chat-id: "-1001234567890".
4. Если бот не видит сообщения: @BotFather → /setprivacy → Disable для бота.

1. Напиши боту /start.
2. getUpdates → "chat":{"id": 2050059107} → chat-id: "2050059107".
3. Или @userinfobot → твой Id.
   Не используй для продакшена с notify-listed: true — заспамит ЛС.

  telegram:
    enabled: true
    bot-token: "123456:ABC..."
    chat-id: "@soul_auction_deals"

  telegram:
    enabled: true
    bot-token: "123456:ABC..."
    chat-id: "-1001234567890"

notifications:
  locale: ru
  notify-listed: true
  notify-sold: true
  notify-expired: false
  min-price: 5000
  telegram:
    enabled: true
    chat-routing: GLOBAL
    bot-token: "123456:ABC..."
    chat-id: "-1001234567890"
    reply-to-listing: true
    notify-price-changed: true

Per-auction (только выбранные аукционы):​

  telegram:
    enabled: true
    chat-routing: PER_AUCTION
    bot-token: "123456:ABC..."

# auctions/regions.yml
telegram-chat-id: "@regions_deals"

Установка плагина SoulAuction:​

Требования​

• Paper 1.21+ или Folia (поддерживается из коробки)
• Плагин экономики— в зависимости от того, что указано в аукционе:
  • Vault + провайдер денег (EssentialsX, CMI и т.п.) — основной вариант
  • PlayerPoints — если аукцион на поинты
  • CoinsEngine — если аукцион на кастомную валюту CE
  • EXPERIENCE / ITEM — без отдельного плагина экономики (уровни / предметы)

Установка (один сервер)​

1. Скачай SoulAuction-2.2.0.jar (или актуальную версию).
2. Останови сервер.
3. Положи .jar в папку /plugins/.
4. Запусти сервер.
5. Дождись первого старта — создастся папка plugins/SoulAuction/ с конфигами, auctions/, lang/, gui/ и т.д.
6. Проверь в игре: /ah — должна открыться витрина.
7. При необходимости отредактируй plugins/SoulAuction/config.yml и plugins/SoulAuction/auctions/global.yml, затем /ah reload.

Первый запуск — что появится​

Сеть прокси (несколько серверов)​

1. В config.ymlна всех инстансах:
   • storage.type: MYSQL + доступ к одной БД
   • redis.enabled: true + один Redis
2. Перезапуск или /ah reload после правок.
3. На каждом сервере — тот же JAR и согласованный конфиг БД/Redis.

Обновление​

1. Останови сервер (или /ah reload только для конфигов/lang — JAR меняется при остановке).
2. Замени старый .jar в /plugins/.
3. Запусти сервер — новые ключи конфига допишутся сами при merge.