Crate

Ящики с добычей со взвешенными наградами, виртуальными ключами, этапами и мини-игрой открытия с выбором карт.

Приватныеv0.0.2Экономика и крафт

ТребуетсяTypeWriter0.9BasicGUI

Создано для сети BornToCraft. Это расширение описано для справки и не распространяется.

Поддержка

Обзор

Crate добавляет на ваш сервер ящики с добычей. У ящика есть список наград, каждая со своей редкостью, а игроки открывают его, тратя виртуальный ключ. Выигрышная награда определяется на сервере до начала какой-либо анимации, поэтому ничто из того, что делает игрок во время открытия, не может изменить результат. Каждое открытие ящика засчитывается в вехи, которые могут запускать дополнительные награды после определённого числа открытий.

Награды — это триггеры TypeWriter, поэтому награда может выдать предмет, выполнить команду, выдать косметику или запустить последовательность. Открытие показывается в мире перед игроком: превью наград на плавающих отображениях предметов или мини-игра с выбором карт. Меню позволяют игрокам просматривать ящики и награды, которые может дать каждый из них.

Расширение работает на сборке BTC для TypeWriter (BTC Core, Paper/Folia) и описано здесь для ознакомления.

Возможности

• Взвешенные награды — у редкостей есть вес, а шанс каждой награды показывается в меню.
• Виртуальные ключи — ключи считаются для каждого игрока в артефакте данных ящика, и при каждом открытии тратится один.
• Безопасные открытия — ключ сначала резервируется и тратится только когда награда раскрыта; отключение, тайм-аут или перезапуск возвращают его.
• Вехи — запускайте дополнительные награды после определённого числа открытий.
• Мини-игра с картами — игрок переворачивает одну из карт рубашкой вверх в сетке, а награда уже определена.
• Превью в мире — награды парят вокруг игрока в раскладках PAGINATED, FLEX или SIMPLE, с необязательным NPC и голограммой.
• Меню — глобальное меню ящиков и меню наград для каждого ящика, с рамками, пагинацией и пользовательскими кнопками.
• Статистика — открытия, ключи, использованные ключи, последнее открытие и веха, доступные как плейсхолдеры.

Установка

1. Установите расширение TypeWriter Basic и расширение GUI (GuiAndDialogs в сборке BTC). Без них Crate не загрузится.
2. Поместите JAR-файл Crate в plugins/Typewriter/extensions/ и перезапустите сервер.
3. Выдайте права из раздела «Права» вашему персоналу.

Начало работы

Создайте ящик с тремя наградами и выдайте себе ключ:

1. В веб-панели TypeWriter откройте страницу manifest и добавьте артефакт Crate Data. Сохраните сгенерированный artifactId и используйте один артефакт на каждый ящик.
2. Добавьте запись Crate. Задайте dataArtifact равным артефакту и напишите noKeyMessage.
3. В rarities добавьте Common с весом 70 и Rare с весом 30.
4. В rewards добавьте три награды: для каждой задайте rarity, item, показываемый в превью, name, а в action — триггер, выдающий награду. Оставьте grantItem включённым, чтобы item выдавался автоматически, или выключите его, если предмет выдаёт само действие.
5. В rewardSlots перечислите слоты инвентаря меню наград (считая с 0), например 10-12. Ящик без слота для наград отказывается открываться.
6. В icon задайте x и y ящика в глобальном меню, item и name.
7. Добавьте действие Open Crate, указывающее на ящик, и запускайте его от NPC, блока или предмета.
8. Опубликуйте, затем выполните /tw crate give <crate entry id> 5 и откройте ящик. Используйте /tw crate menu, чтобы просматривать ящики.

Клики по наградам в меню наград

В меню наград ящика клик по награде напрямую запускает action этой награды, без траты ключа и без статистики. Не давайте игрокам доступ к меню наград, если действие награды выдаёт что-то ценное, либо оставьте это меню для персонала.

Выдача ключей

Ключи добавляются командой /tw crate give <crate> <amount> [targets]. Отдельного действия для ключей нет, но действие-команда может выполнить эту команду, например в награде за квест или в магазине.

Как это работает

Шанс награды — это вес её редкости, делённый на общий вес всех наград. У награды, чья редкость не указана в rarities, вес равен 1. Когда награда раскрыта, ключ тратится, счётчики открытий и использованных ключей растут, срабатывает любая пройденная веха, затем выдаётся предмет (если включён grantItem) и выполняется action награды. У игрока может быть только одно открытие одновременно.

Меню

• Глобальное меню — открывается командой /tw crate menu. Оно показывает по одному значку на ящик, размещённому в x (от 0 до 8) и y (от 0 до 5) значка, а клик по значку открывает меню наград этого ящика. Необязательная запись Crate Main Menu задаёт размер, заголовок, рамку, кнопки, число предметов на странице и столбец, зарезервированный под стрелки пагинации.
• Меню наград — открывается кликом по значку или действием Open Crate Menu. Оно показывает награды в rewardSlots с их названием, описанием (lore) и необязательными строками шанса и редкости (chanceLore и rarityLore, использующие {chance} и {rarity}). guiLayout — это PAGINATED, FLEX (по центру, четыре столбца) или SIMPLE. frameItem, itemsPerPage и paginationColumn настраивают рамку и пагинацию, а buttons добавляют пользовательские кнопки с действием.

У кнопок есть тип (INFORMATION, NEXT, PREVIOUS, FILL) и позиция. Кнопка FILL копируется в каждый пустой слот. Маркеры crate_button: (CRATE_OPEN, CRATE_PREVIEW, CRATE_GLOBAL_BROWSE, CRATE_REWARD_SLOT, NAV_BACK, NAV_CLOSE) предлагаются в редакторе GUI, но в этой версии они показывают лишь предмет-заглушку.

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

У Crate нет файла конфигурации. Всё настраивается в записях. Данные игроков хранятся в артефакте Crate Data: ключи, открытия, использованные ключи, время последнего открытия, веха и незавершённые открытия. Запись выполняется асинхронно, а незавершённые открытия, оставшиеся после сбоя, восстанавливаются при запуске (ключ возвращается).

Команды

Все команды — это подкоманды команды TypeWriter, поэтому они начинаются с /typewriter или /tw. <crate> — это запись ящика, она дополняется автоматически.

Команда	Описание	Право
/tw crate menu	Открывает глобальное меню ящиков.	typewriter.crate.menu
/tw crate open <crate>	Открывает ящик, тратя один ключ.	typewriter.crate.open
/tw crate give <crate> [targets]	Выдаёт один ключ вам или выбранным игрокам.	typewriter.crate.give
/tw crate give <crate> <amount> [targets]	Выдаёт несколько ключей.	typewriter.crate.give
/tw crate remove <crate> [targets]	Убирает один ключ, только если он есть у игрока.	typewriter.crate.remove
/tw crate remove <crate> <amount> [targets]	Убирает несколько ключей, только если их достаточно у игрока.	typewriter.crate.remove

Базовое право typewriter.crate защищает всю команду. Расширение регистрирует внутреннюю команду /cratemenu, используемую кликами в меню; её не нужно вводить вручную.

Права

Право	Что даёт
typewriter.crate	Доступ к команде /tw crate.
typewriter.crate.menu	/tw crate menu.
typewriter.crate.open	/tw crate open.
typewriter.crate.give	/tw crate give.
typewriter.crate.remove	/tw crate remove.

Плейсхолдеры

Это теги MiniPlaceholders расширения crate. Замените id идентификатором записи ящика. Неизвестный ящик возвращает пустое значение.

Плейсхолдер	Возвращает
<crate_openings:id>	Число открытий этого ящика игроком.
<crate_keys:id>	Ключи, которые есть у игрока.
<crate_keys_used:id>	Ключи, которые игрок потратил.
<crate_last_open:id>	Время последнего открытия в миллисекундах с 1 января 1970 года.
<crate_milestone:id>	Наивысшая достигнутая веха.

В hologramLines вместо этого используйте токены {openings}, {keys}, {last_open} и {milestone}.

Записи

Записей: 6, сгенерированы из исходного кода расширения.

Действия2

• Open CrateOuvre une caisse
• Open Crate MenuOuvre le menu d'une caisse

Артефакты1

• Crate ArtifactDonnées de caisse

Манифесты3

• CrateDéfinition d’une caisse
• Crate Main MenuApparence du menu principal
• Crate Minigame CardsMini-jeu Caisse : Cartes

Устранение неполадок

«This crate is not configured correctly». Ящик не прошёл проверку, а лог сервера перечисляет причины: нет наград, недопустимый вес редкости (он должен быть больше нуля), нет rewardSlots либо слоты вне диапазона 0–53 или повторяются, кнопка или icon вне сетки 9 на 6, либо вехи при нуле открытий или повторяются. Те же проверки выполняются при запуске и записывают предупреждение.

Игрок получает noKeyMessage. У игрока нет ключа для этого ящика, либо у ящика нет dataArtifact. Выдавайте ключи командой /tw crate give и проверьте связь с артефактом.

«You are already opening a crate». Для этого игрока уже идёт открытие. Оно заканчивается, когда награда раскрыта или игрок отключился.

Статистика и ключи не меняются после открытия. Они меняются только когда награда раскрыта. Если игрок вышел или сервер остановился до этого, ключ возвращается, а счётчики остаются прежними.

Превью ничего не показывает или показывает не те награды. Превью использует item каждой награды. Награды с пустым item пропускаются, а preview.maxVisibleRewards ограничивает, сколько показывается одновременно. preview.distance и смещения *Location перемещают отображение.

Мини-игра с картами не запускается. Свяжите запись Crate Minigame: Cards в поле minigame ящика. Её columns — до 10, rows — до 10, а cardCount ограничено 100.

Награда выдаётся дважды. Оставляйте grantItem включённым, только если action не выдаёт предмет тоже.

Связанные расширения

• GUI — движок меню, используемый для меню ящиков.