BattlePass
Обзор
BattlePass добавляет на ваш сервер сезонную линию прогрессии. У сезона есть дата начала и дата окончания, и он разбит на недели; каждая неделя открывает список квестов. Когда игрок завершает один из этих квестов, он получает опыт, а пороги опыта превращаются в уровни. Награды сгруппированы по тирам (например, бесплатный тир и премиум-тир, защищённый правом) и забираются из меню.
Всё настраивается в одной записи Battle Pass Definition в веб-панели: тиры, награды, недели, пороги опыта, расписание, макет меню и предметы кнопок. Награда — это просто список триггеров TypeWriter, поэтому она может выдавать предметы, выполнять команды, выдавать косметику или делать всё, что может любое действие. Квесты берутся из расширения TypeWriter Quest.
Расширение работает на сборке BTC TypeWriter (BTC Core, Paper/Folia) и документировано здесь для справки. Прогресс сохраняется через артефакт Battle Pass Data, который хранится в кэше в памяти, поэтому меню и плейсхолдеры никогда не ждут хранилища.
Возможности
- Сезоны — необязательные даты начала и окончания, длительность недели в днях и часовой пояс IANA (по умолчанию UTC).
- Еженедельные квесты — недели открываются автоматически или в выбранную дату, а каждый квест при завершении даёт фиксированное количество опыта.
- Опыт и уровни — список порогов опыта определяет уровни, с необязательным ограничением опыта.
- Награды по тирам — у каждого тира есть приоритет, необязательное право и награды, привязанные к требуемому уровню.
- Безопасное получение — получение резервируется до запуска триггеров, поэтому награда не может быть выдана дважды.
- Настраиваемые меню — слоты, размеры и предмет, название и описание каждой кнопки либо полностью пользовательский макет на основе расширения GUI.
- Административные команды — добавление, удаление или установка опыта и уровней для себя или других игроков и просмотр прогресса игрока.
- Плейсхолдеры — уровень, опыт, счётчики наград и информация о неделях для скорбордов и меню.
- Редактируемые сообщения — каждое сообщение в чате можно изменить в записи BattlePass Messages.
- Готов к сети серверов — прогресс хранится через расширение MySQL с инвалидацией кэша по Redis, когда он доступен.
Установка
- Установите расширение TypeWriter Quest, расширение GUI (
GuiAndDialogsв сборке BTC) и расширение MySQL. TypeWriter не загрузит BattlePass без них. - Положите JAR-файл BattlePass в
plugins/Typewriter/extensions/и перезапустите сервер. - Создайте квесты, которые хотите использовать, с помощью расширения Quest.
- Если вам нужен премиум-тир, создайте право в вашем плагине прав (название на ваше усмотрение, вы вводите его в тире).
Быстрый старт
Создадим четырёхнедельный сезон с бесплатной наградой на уровне 1:
- В веб-панели TypeWriter откройте страницу manifest и добавьте артефакт Battle Pass Data. Оставьте
artifactIdсгенерированным и держитеstorage.modeравнымPLAYER. - Добавьте запись Battle Pass Definition на той же странице. Задайте
name, укажите вdataартефакт и выберитеicon, напримерminecraft:book. - В
xpзаполнитеlevelsвозрастающими порогами опыта (например100,250,500) и при желанииmax. - В
weeksдобавьте неделю сnumber1,titleи вquestsвыберите запись Quest и задайте ейxpReward. Повторите для следующих недель. - В
scheduleзадайтеstart(например2026-11-01T00:00:00),weekDurationDaysиtimezone(напримерEurope/Paris). Тогда недели открываются одна за другой. - В
tiersдобавьте тир сlevel1, а вrewardsдобавьте награду сlevelRequired1иdisplayName. Свяжитеtriggers, выдающие награду, например действие, выдающее предмет. - Добавьте действие Open Battle Pass, указывающее на ваше определение в
battlePass, и запустите его из NPC, предмета или меню. Игроки также могут ввести/tw battlepass. - Опубликуйте, завершите квест недели и откройте меню, чтобы получить награду.
level тира — это его номер в меню наград, и он должен быть уникальным внутри определения. Уровень игрока, необходимый для получения награды, — это собственный levelRequired награды. У тира может быть permission: игроки без него видят его награды заблокированными, именно так строится премиум-линия.
У каждой награды есть id. Если оставить его пустым, расширение сгенерирует его из уровня тира и позиции награды (tier-1-reward-1), но если позже вы переместите награды или вставите новые, сгенерированные id сдвинутся, и полученные игроками награды перестанут совпадать. Задайте явный id каждой награде до начала сезона и никогда его не меняйте.
Как это работает
Опыт начисляется, только когда квест из списка одной из недель определения переходит в COMPLETED, неделя отмечена как available, неделя открыта и сезон идёт. Квест с xpReward равным 0 ничего не даёт. Уровень — это число порогов xp.levels, которых достиг игрок.
Награду можно получить, когда сезон начался (получение остаётся возможным и после окончания), уровень игрока достигает levelRequired и у него есть permission тира, если оно задано. Награды получаются один раз. Если триггеры награды завершились ошибкой, награда остаётся ожидающей и сама не повторяется, потому что у триггеров могут быть побочные эффекты.
Меню
По умолчанию расширение открывает собственные меню-инвентари: главное меню со списком недель, меню квестов выбранной недели и меню наград (тиров).
- Главное меню — по одной кнопке на неделю, кнопки предыдущей и следующей недели, кнопка наград, информационная кнопка и кнопка закрытия.
- Меню квестов — квесты недели с их состоянием (заблокирован, доступен, активен, завершён), кнопки страниц, кнопка сортировки и кнопка «назад».
- Меню наград — награды каждого тира с их состоянием, кнопки страниц и кнопка «назад»; клик по разблокированной награде получает её.
Размеры и позиции берутся из layout. Каждый размер должен быть кратен 9 в диапазоне от 9 до 54, а каждый слот должен в него помещаться. Слоты принимают одиночные числа или диапазоны вроде 10-16. Оставьте слот пустым, чтобы использовать позицию по умолчанию (макет на 54 слота с неделями в ряду 2, квестами в рядах с 2 по 4 и закрытием в слоте 49), либо отключите кнопку полем ...Enabled. У каждой кнопки есть item, name и lore в buttons, где можно использовать плейсхолдеры в фигурных скобках, такие как {week_title}, {quest_name}, {tier_level} или {reward_state}. В подсказке к полю в панели перечислены плейсхолдеры, доступные для каждой кнопки.
Если вы задаёте baseMenuId, menuLayoutPool, menuViews или menuMainLayoutId, пропуск открывается внутри вашего собственного шасси GUI с тремя представлениями (главное, уровни, квесты), чьи id задаются в menuHomeViewId, menuLevelsViewId и menuQuestsViewId. Редактор GUI тогда предлагает предметы battlepass_button:: WEEK_SLOT, TIER_MENU, REWARD_SLOT, CLAIM, QUEST_SLOT, SORT, INFO, PAGE_NEXT, PAGE_PREV, BACK и CLOSE. Описания типов кнопок в редакторе на французском языке.
Взаимодействия меню внутренние для сессии GUI: это не команды Bukkit, и игроки не могут вводить их вручную.
Команды
Команды BattlePass являются подкомандами команды TypeWriter, поэтому начинаются с /typewriter или её псевдонима /tw. Базовое право — typewriter.battlepass. Аргумент <pass> — это id или название Battle Pass Definition, он автодополняется. Необязательный аргумент [targets] — селектор игроков; без него команда применяется к отправителю.
| Команда | Описание |
|---|---|
/tw battlepass | Открывает меню первого определения, отсортированного по id. |
/tw battlepass menu | То же, что /tw battlepass. |
/tw battlepass open | То же, что /tw battlepass. |
/tw battlepass <pass> xp add <amount> [targets] | Добавляет опыт (знак количества игнорируется). |
/tw battlepass <pass> xp remove <amount> [targets] | Убирает опыт. |
/tw battlepass <pass> xp set <amount> [targets] | Задаёт опыт (не ниже нуля). |
/tw battlepass <pass> level add <amount> [targets] | Повышает уровень. |
/tw battlepass <pass> level remove <amount> [targets] | Понижает уровень. |
/tw battlepass <pass> level set <amount> [targets] | Задаёт уровень. |
/tw battlepass <pass> info [targets] | Показывает опыт и уровень игрока для пропуска. |
Права
| Право | Даёт доступ к |
|---|---|
typewriter.battlepass | Всем командам /tw battlepass, включая меню и административные подкоманды. |
permission тира | Право на ваш выбор, заданное у тира, необходимое для получения наград этого тира. |
Плейсхолдеры
Это теги MiniPlaceholders расширения battlepass, которые можно использовать в любом тексте MiniMessage с поддержкой плейсхолдеров. Замените def на id записи Battle Pass Definition. Счётчики — числа; значения «истина или ложь» возвращаются как 1 или 0.
| Плейсхолдер | Возвращает |
|---|---|
<battlepass_name:def> | Название пропуска. |
<battlepass_active:def> | 1, пока игроки могут получать опыт (сезон идёт), иначе 0. |
<battlepass_level:def> | Уровень игрока. |
<battlepass_xp:def> | Опыт игрока. |
<battlepass_xp_max:def> | Ограничение опыта или наибольший порог, если ограничение не задано. |
<battlepass_xp_next:def> | Порог опыта следующего уровня. |
<battlepass_xp_remaining:def> | Сколько опыта не хватает до следующего уровня. |
<battlepass_rewards:def> и <battlepass_rewards_total:def> | Общее число наград. |
<battlepass_rewards_claimed:def> | Уже полученные награды. |
<battlepass_rewards_available:def> | Награды, которые игрок может получить сейчас. |
<battlepass_rewards_unclaimed:def> | Все награды минус полученные. |
<battlepass_rewards_pending:def> | Награды, зарезервированные, но ещё не выданные. |
<battlepass_week_state:def:N> | Подпись состояния недели N. |
<battlepass_week_active:def:N> | 1, когда неделя N не заблокирована и не недоступна. |
<battlepass_week_available:def:N> | 1, когда неделя отмечена как available. |
<battlepass_week_title:def:N> | Заголовок недели N. |
<battlepass_week_description:def:N> | Описание недели N. |
<battlepass_week_release:def:N> | Дата открытия недели N. |
<battlepass_week_release_in:def:N> | Время до открытия недели N, пусто после открытия. |
Записи
Записей: 5, сгенерированы из исходного кода расширения.
Действия1
- Open Battle PassOpen a battle pass menu
Факты1
- Battle Pass Quest ActiveCheck if a battle pass week is active
Артефакты1
- Battle Pass Data ArtifactStore battle pass runtime data
Манифесты1
- Battlepass DefinitionRegister a battle pass definition
Другие записи1
- Battlepass MessagesBattlePass Messages
Устранение неполадок
Расширение не загружается. BattlePass требует расширения Quest, GUI (GuiAndDialogs) и MySQL. Проверьте журнал запуска TypeWriter на предмет отсутствующей зависимости.
В логе написано «Ignoring invalid battle pass definition». Определение не прошло проверку, поэтому не зарегистрировано, а /tw battlepass отвечает «Aucun Battle Pass n'est actuellement chargé». В строке лога перечислены проблемы: пустое name, размер меню, не кратный 9 в диапазоне от 9 до 54, слот за пределами меню, повторяющиеся уровни тиров, номера недель или id наград, xp.levels, не строго возрастающие, либо schedule.start, не предшествующий schedule.end.
Завершение квеста не даёт опыта. Квест должен быть указан в неделе определения с xpReward больше 0, неделя должна быть available и открыта, сезон должен быть активен, а определению нужен артефакт data (лог предупреждает, когда его нет). Неизвестный timezone заменяется на UTC, а строки дат, которые не удаётся разобрать, игнорируются.
Награду нельзя получить. Уровень должен достигать levelRequired, у игрока должно быть permission тира, сезон должен начаться, а награда не должна быть уже получена или ожидающей. Если её триггеры завершились ошибкой, лог сообщает «remains pending after delivery failure», и награда остаётся ожидающей, пока администратор не решит, что делать.
Полученные награды снова появляются после редактирования наград. Id наград, сгенерированные по позициям, изменились. Задайте каждой награде явный id и не меняйте его.
Прогресс не сохраняется. artifactId артефакта должен оставаться корректным UUID, сгенерированным веб-панелью; расширение отказывается использовать что-либо другое. Не перемещайте и не переименовывайте сохранённые файлы вручную.