pnClans v1.2.1 — Stability Update: Shop, Quests & Battle Lobby

pnClans v1.2.1 — Stability Update: Shop, Quests & Battle Lobby

Кратко

v1.2.1 — стабилизационный релиз после большого обновления v1.2.0. Основной фокус версии — клановый магазин, квесты, организованные клановые битвы, MMR и конфигурация.

Главная задача обновления — убрать опасные сценарии частичных покупок и потерянных наград, сделать битвы понятными и управляемыми через полноценный Battle Lobby, отделить официальный боевой MMR от обычного PvP и перенести новые изменяемые параметры и сообщения в конфигурацию.

После знакомства с обновлением присоединитесь к Discord: https://discord.gg/TFdnyvMft. В канале «Отзывы» можно оставить общий отзыв, сообщить о баге или предложить идею для следующей версии.

Для игроков

• Добавлен полноценный Battle Lobby после принятия кланового вызова.
• Принятие вызова больше не запускает бой мгновенно и не телепортирует случайный состав на арену.
• Игроки могут самостоятельно войти в боевой состав или выйти из него.
• Стороны подтверждают готовность через состояние READY.
• После готовности обеих сторон запускается настраиваемый обратный отсчёт перед переносом на арену.
• Если выбранный участник выходит с сервера или состав меняется, готовность сбрасывается и старт отменяется до повторного READY.
• Составы больше не формируются автоматически по алфавиту из первых онлайн-участников клана.
• Улучшено меню клановых битв: отображаются состояния lobby, countdown, составы, READY/WAIT, соперник, счёт и доступное следующее действие.
• Улучшена защита friendly fire: теперь учитываются не только прямые удары игрока, но и снаряды, выпущенные игроком.
• Обычные PvP-убийства в мире больше не изменяют официальный клановый MMR.
• MMR теперь изменяется через организованные клановые битвы, что делает рейтинг значительно устойчивее к фарму обычных убийств.
• Требования магазина по квестам теперь проверяют завершение квеста в текущем цикле, а не одно историческое завершение навсегда.
• Покупки в клановом магазине получили более точные причины отказа вместо одного общего сообщения.
• При проблемах с валютой, журналом покупок или наградой магазин теперь сообщает более корректный результат и не продолжает опасную операцию вслепую.
• Награды квестов больше не теряются только потому, что нужный получатель временно офлайн: ожидающая выдача сохраняется и обрабатывается при доступности игрока.

Для администраторов

• Существенно расширена настройка battles.yml.
• Добавлена настройка времени жизни Battle Lobby.
• Добавлена настройка длительности countdown перед стартом боя.
• Добавлена настройка автоматического включения организаторов вызова в первоначальный состав.
• Добавлена настройка сохранения инвентаря при смерти в организованной битве.
• Добавлена отдельная настройка сохранения уровня и опыта.
• Добавлена настройка friendly fire внутри организованных битв.
• Добавлена настройка принудительного удержания участников внутри радиуса арены.
• Добавлена настройка технического поражения, когда у стороны не остаётся онлайн-участников.
• Добавлен настраиваемый порог подсветки соперников с близким MMR.
• Расширена конфигурация отображения Battle GUI: материалы, состояния, READY/WAIT, форматы счёта, причины пустого списка, действия и тексты интерфейса.
• Новые игровые сообщения Battle Lobby перенесены в messages.yml и используют стандартную Action-систему pnClans.
• Добавлены отдельные сообщения для открытия lobby, входа/выхода из состава, READY, countdown, изменения состава, офлайн-участника, истечения времени, ошибки арены, отмены старта, ошибки телепортации и других состояний.
• Добавлены конфигурируемые сообщения для новых общих отказов и отключённых модулей, которые раньше местами выводились напрямую из кода.
• Добавлен безопасный backfill новых параметров: существующие YAML-файлы дополняются недостающими ключами без намеренного сброса уже загруженных пользовательских значений.
• shop.enabled теперь проверяется непосредственно сервисом покупки, а не только видимостью кнопки GUI.
• Повреждённый shop-purchases.json больше не сбрасывается молча в пустое состояние. Магазин закрывает покупки до исправления файла и перезагрузки, чтобы не обнулить дневные лимиты.
• Запись дневного лимита покупки выполняется до выдачи необратимых наград.
• Сохранение shop-purchases.json выполняется через временный файл и атомарную замену, когда файловая система это поддерживает.
• Перед списанием валюты магазин предварительно валидирует детерминированные награды: материалы, сериализованные предметы, enchantments, console commands, barter/chance-конфигурацию.
• Возврат валюты теперь имеет реальный результат успеха/ошибки для Clan Points, Vault и PlayerPoints.
• Ошибка возврата денег больше не игнорируется молча и отдельно журналируется.
• Добавлен новый quest-rewards.json — журнал доставки наград квестов.
• Завершение квеста теперь не фиксируется, если невозможно надёжно записать информацию о будущей выдаче награды.
• Награды квестов используют состояния PENDING, CLAIMING, DELIVERED и FAILED, чтобы уменьшить риск дублей после сбоя или рестарта.
• Неоднозначная награда, которая могла быть выдана непосредственно перед аварийным завершением сервера, не повторяется автоматически: сервер пишет подробную ошибку для ручной проверки вместо потенциального дюпа.

Клановый магазин

Исправлено

• Убрано опасное поведение, при котором валюта могла быть возвращена после уже частично выданной необратимой награды, создавая возможность бесплатной частичной покупки.
• Добавлено различие между полной ошибкой награды и ситуацией, когда выдача уже началась (REWARD_PARTIAL).
• Если выдача ещё не началась, магазин может безопасно вернуть валюту и снять зарезервированный лимит покупки.
• Если выдача уже началась, автоматический refund не выполняется, чтобы не создавать дюп; ситуация подробно записывается в лог.
• Ошибка сохранения purchase ledger больше не остаётся незамеченной после списания средств.
• Исправлена проверка успешности refund через Vault и Clan Points.
• Добавлена проверка фактического результата возврата через PlayerPoints.
• Добавлена предварительная валидация статической награды и настраиваемых Actions до списания валюты.
• Повреждение purchase ledger теперь переводит магазин в безопасный режим вместо молчаливого обнуления лимитов.

Добавлено

• Причины отказа SHOP_DISABLED, LEDGER_FAILED, REFUND_FAILED, REWARD_FAILED и REWARD_PARTIAL.
• Резервирование дневной покупки до выполнения необратимых Actions.
• Безопасное снятие резерва, если награда не начала выполняться и средства были возвращены.
• Более подробное серверное журналирование проблем покупки.

Клановые квесты

Исправлено

• Прогресс обычного шага квеста теперь откатывается в памяти, если saveClan() завершился ошибкой.
• Завершение квеста больше не сохраняется раньше, чем создана надёжная запись доставки его награды.
• Награда для LEADER больше не зависит от того, находится ли лидер онлайн непосредственно в момент завершения.
• Для ACTOR, если конкретный actor отсутствует, используется безопасный fallback на лидера клана, когда это возможно.
• Клановые очки и Action-награды теперь отслеживаются отдельно по состояниям доставки.
• Требования магазина к повторяемым квестам больше не остаются открытыми навсегда после единственного исторического завершения.

Добавлено

• Долговечная очередь выдачи наград quest-rewards.json.
• Выдача ожидающих наград при запуске и при входе игрока.
• Защита от автоматического повторения неоднозначно выданной награды после crash/restart.

Клановые битвы

Изменено

Старый цикл:

Challenge -> Accept -> автоматический выбор первых online-игроков -> мгновенный teleport -> Battle

Новый цикл:

Challenge -> Accept -> Battle Lobby -> выбор состава -> READY обеих сторон -> Countdown -> Teleport -> Battle -> Result -> Return

Добавлено

• Отдельное состояние Battle Lobby.
• Ручной состав каждой стороны.
• Вход и выход игрока из боевого состава.
• READY каждой стороны.
• Настраиваемый countdown.
• Сброс READY при изменении состава.
• Проверка выбранных участников непосредственно перед стартом.
• Отмена старта, если участник вышел с сервера.
• Отдельное резервирование арены для lobby до начала боя.
• Настраиваемые сообщения всех этапов lobby.
• Новые состояния и placeholders для GUI битв.

Удалено / заменено

• Удалён автоматический выбор первых онлайн-участников клана по алфавиту.
• Удалён мгновенный старт организованной битвы сразу после принятия вызова.
• Удалено автоматическое изменение MMR за обычные PvP-убийства и смерти в открытом мире (+10 / -5).
• Официальный MMR оставлен за организованными клановыми битвами.

Конфигурация

Версия продолжает переход pnClans к configuration-driven архитектуре.

• messages.yml отвечает за игровые сообщения и Action-уведомления.
• battles.yml отвечает за механику и отображение клановых битв.
• Новые изменяемые значения Battle Lobby не зафиксированы в сервисной логике без возможности настройки.
• При обновлении недостающие новые ключи могут быть добавлены автоматически через backfill.
• Существующие пользовательские значения не должны намеренно заменяться дефолтными только из-за появления новой версии схемы.

Полный перенос всех старых меню и старых сообщений плагина в configuration-driven формат не является частью v1.2.1 и будет продолжен отдельно, чтобы не смешивать стабилизационный релиз с большим UI/config рефакторингом.

Технические изменения

• CI теперь проверяет и собирает pnClans отдельно под Java 21 и Java 25.
• Release содержит два самостоятельных Shadow JAR.
• Улучшена обработка Projectile в проверке friendly fire.
• Добавлена защита от продолжения покупки при неисправном purchase ledger.
• Добавлена долговечная модель выдачи наград квестов с защитой от повторной выдачи.
• Улучшена диагностика ошибок магазина и квестовых наград.
• Сохранена совместимость текущего публичного API v5; этот стабилизационный релиз не требует очередного повышения API-версии.

Совместимость

• Minecraft / Paper: целевая версия сборки — Paper 1.21.11.
• Java: доступны отдельные сборки для Java 21 и Java 25.
• Vault продолжает использоваться как поддерживаемая экономика магазина.
• PlayerPoints остаётся дополнительной валютой магазина при наличии соответствующего плагина.
• PlaceholderAPI остаётся дополнительной интеграцией.

Как обновиться с v1.2.0

1. Сделайте резервную копию папки plugins/pnClans/ и базы данных.
2. Выберите JAR под Java вашего сервера:
   • pnClans-1.2.1-java21-all.jar
   • pnClans-1.2.1-java25-all.jar
3. Замените старый JAR pnClans.
4. Полностью перезапустите сервер.
5. Проверьте battles.yml и messages.yml: новые параметры будут доступны через конфигурацию/backfill.
6. Если модуль битв был отключён, сначала настройте и протестируйте арену, затем включайте его.
7. Не удаляйте shop-purchases.json ради обхода ошибки: если файл повреждён, исправьте или восстановите его из резервной копии.
8. Новый quest-rewards.json создаётся автоматически и используется для безопасной доставки квестовых наград.

Важно

• Активные организованные бои, lobby и ожидающие challenge по-прежнему являются runtime-состоянием и не предназначены для восстановления как продолжающийся матч после полного рестарта сервера.
• Произвольные Action-награды могут иметь необратимые внешние эффекты. Если сторонняя команда или Action падает уже после начала выдачи, pnClans намеренно не делает автоматический refund, чтобы не создавать бесплатные дубли наград.
• Для неоднозначных квестовых наград после аварийного завершения сервера приоритет отдаётся защите от дюпа: такие записи помечаются для ручной проверки вместо автоматического повторения.

---

pnClans v1.2.1 — это фундамент для следующего крупного этапа. После стабилизации магазина, квестов, Battle Lobby и MMR можно безопаснее развивать Ranked, Seasons, Divisions и более крупные клановые режимы.