Pets
Обзор
Pets добавляет коллекционных компаньонов, вдохновлённых EcoPets. Каждый питомец определяется один раз в веб-панели (Pet Definition), а у каждого игрока есть свои копии. Питомец выдаётся как предмет-жетон: правый клик по жетону добавляет питомца в меню компаньонов игрока. Из меню игрок активирует одного питомца за раз, и этот питомец парит над его головой, идёт рядом с ним или летает вокруг него.
Питомцы получают опыт, когда владелец убивает мобов или когда ваша история выдаёт опыт, и повышают уровень по формуле или таблице, которую вы пишете. Питомец может отвечать мобам, ударившим владельца, и может иметь несколько скинов, открываемых через критерии TypeWriter.
Возможности
- Три режима отображения —
HEADпарит над игроком,GROUNDидёт рядом,FLYпарит на заданной высоте. - Меню компаньонов — GUI с сеткой имеющихся питомцев, активацией, скрытием и показом, подробностями и скинами.
- Предметы-жетоны — питомцы переходят между игроками как предметы, сохраняющие уровень, опыт, режим и скин.
- Опыт и уровни — формула вроде
{level} * 100или явная таблица, с максимальным уровнем. - Опыт за убийства и за сюжет — опыт за убийство моба, а также действие для выдачи опыта из любой последовательности.
- Ответный удар — необязательная контратака мобов, ранивших владельца, с уроном в зависимости от уровня.
- Скины — несколько скинов NPC на питомца, у каждого свои критерии, приоритет и значок в меню.
- Права на слоты — закрывайте слоты меню правами, чтобы продавать дополнительные слоты компаньонов.
- Плейсхолдеры — название, уровень, опыт, статус и принадлежность активного питомца, слота или любого питомца.
- Поддержка моделей — наземные и летающие питомцы используют любое определение сущности, включая модели ModelEngine.
Установка
- Установите расширение GUI, которое рисует меню.
- По желанию: установите ModelEngine и расширение TypeWriter, предоставляющее ваши модели как определения сущностей, если питомцы должны использовать анимированные модели.
- Поместите JAR-файл Pets в
plugins/Typewriter/extensions/и перезапустите сервер. - Создайте артефакт Pet Storage, чтобы имеющиеся питомцы сохранялись, см. Начало работы.
Начало работы
Создайте первого питомца и выдайте его игроку:
- В веб-панели TypeWriter откройте static-страницу и добавьте артефакт Pet Storage. Без него расширение пишет в лог «No pet_storage entry found», и ничего не сохраняется.
- Добавьте Pet Definition. Собственный
nameзаписи — это отображаемое имя питомца, а еёid— идентификатор питомца. - Выберите
defaultMode. ДляHEADпри желании вставьтеtextureв base64 для парящей головы. ДляGROUNDилиFLYзадайтеnpcравным записи определения сущности, которая будет появляться рядом с игроком. - В разделе
xpзадайтеmaxLevelи либоformulaс{level}(например,{level} * 100), либо списокlevels. ЗадайтеkillRewardдля опыта за убийство. - По желанию: включите
combat.enabledдля ответного удара и настройтеtoken(предмет, его название и описание, свечение). - Добавьте действие Pets Open Menu, задайте его
storageравным вашему артефакту Pet Storage и запускайте его от NPC, предметом или командой. - Опубликуйте, затем выполните от имени игрока
/pets give <pet> 1. Кликните правой кнопкой по жетону, затем откройте меню и кликните по питомцу, чтобы активировать его.
Чтобы выдавать опыт из вашей истории, добавьте действие Pets Add XP с amount. Опыт получает активный питомец игрока. Чтобы управлять конкретным питомцем, используйте Pets State с pet и action.
Действия, которое напрямую открывало бы питомца, нет. Питомец попадает к игроку как предмет-жетон, через /pets give или кнопку «вернуть в предмет» в меню. Выполняйте команду из действия консольной команды в квесте или магазине, чтобы сделать её открываемой наградой.
Как это работает
У игрока может быть не более одного питомца на каждое определение. Одновременно активен только один питомец: активация другого деактивирует первого. Питомцы сохраняются в артефакт Pet Storage в фоновом режиме, а активный питомец восстанавливается, когда игрок заходит на сервер.
Режимы отображения.
HEADпоказывает питомца над головой игрока с применениемheadOffset. Если заданnpc, используется эта сущность. В противном случае невидимая стойка для брони носит голову игрока сtexture.GROUNDсоздаётnpc(или NPC выбранного скина) в нескольких блоках позади игрока и заставляет его следовать.swimModeопределяет, плавает ли он в жидкостях:AUTOследует возможностям сущности,ALWAYSиNEVERзадают принудительно.FLY— то же, чтоGROUND, но питомец парит наflightHeightблоков над игроком.
Если у питомца GROUND или FLY нет NPC (или ни один из его скинов не подходит), он не показывается, а в лог записывается предупреждение. Над каждым активным питомцем показывается подпись с названием и уровнем. Режим берётся из defaultMode при первом создании жетона и остаётся с этим экземпляром питомца.
Опыт и уровни. Питомец начинает с 1 уровня. Каждая запись levels задаёт общий опыт, который должен набрать питомец для уровня, например 2 уровень при 100 опыта, 3 уровень при 250 опыта. Явные записи приоритетнее формулы. Формула вычисляется с заменой {level} на достигаемый уровень и поддерживает + - * /, скобки и десятичные дроби. Питомец без требования для следующего уровня уровень не повышает.
Ответный удар. При combat.enabled активный и видимый питомец отвечает любому мобу, не являющемуся игроком, который наносит урон владельцу, после небольшой задержки и с перезарядкой 1,5 секунды на каждого нападающего. Урон — это damage самой высокой записи levels, не превышающей уровень питомца. Если её нет, это 1,5 плюс 0,5 за каждый уровень выше 1.
Скины. Каждая запись skins указывает на определение NPC, priority и criteria. Питомец использует скин, выбранный игроком, если его критерии всё ещё выполняются, иначе скин с наивысшим приоритетом, критерии которого выполняются. Поле npc определения — это запасной скин. Записи скина нужен npc, иначе она игнорируется.
Меню
Действие Pets Open Menu открывает встроенное меню компаньонов с заголовком «Compagnons». Каждый имеющийся питомец — это значок-голова игрока, показывающий уровень, прогресс опыта и состояние. Левый клик активирует или деактивирует питомца, правый клик открывает экран подробностей. Экран подробностей показывает характеристики и позволяет игроку активировать питомца, выбрать скин (если у питомца их больше одного), вернуть питомца в предмет или вернуться назад. Кнопка в левом нижнем углу показывает или скрывает активного питомца.
Параметры меню — это поля объекта menu действия:
slots— номера слотов инвентаря, где показываются питомцы. По умолчанию 21 слот в трёх рядах.lockedSlots— парыslotиpermission. Слот, права на который у игрока нет, показывает маркер блокировки, и в него нельзя поместить питомца.maxSlots— максимальное число используемых слотов (по умолчанию 21, минимум 1): раскладываются и могут получить нового питомца только первыеmaxSlotsзаписейslots. Параметр ограничивает раскладку и число питомцев, которых игрок может получить, но не тех, что у него уже есть.rows— высота меню, от 1 до 6.storage— используемый артефакт Pet Storage.
Раскладка слотов последнего открытого меню сохраняется вместе с данными игрока и определяет, какие слоты может занять жетон. Питомец, которым игрок уже владеет в слоте за пределами maxSlots (или за пределами высоты меню), не скрывается: он показывается в свободной ячейке меню, никогда на кнопке показа/скрытия, а клики по нему по-прежнему действуют на его собственный слот. Если таких питомцев больше, чем свободных ячеек, остальные остаются во владении и показываются на странице Pets общего меню Social, где перечислены все имеющиеся питомцы; предупреждение записывается в журнал один раз для каждого игрока.
Использование в вашем собственном меню. Расширение регистрирует префикс кнопок pets_button: для любого меню GUI. Задайте buttonPrefix предмета равным pets_button:, а его buttonType — одним из значений:
buttonType | Показывает |
|---|---|
PET_ENTRY | Питомца в этой позиции в списке игрока. Левый клик переключает его, правый клик выбирает его для предметов подробностей. |
PET_DETAIL_INFO | Уровень, опыт и режим выбранного питомца. |
PET_LEVEL_ENTRY | Один уровень выбранного питомца с требованием по опыту и состоянием. |
PET_DETAIL_REMOVE | Кнопку, возвращающую выбранного питомца в предмет. |
PET_LIST_NAV, PET_DETAIL_NAV | Стрелки страниц для списка питомцев и списка уровней. |
Слоты также могут выполнять команды pet_menu: pet_menu activate <slot>, pet_menu deactivate <slot>, pet_menu toggle_visibility, pet_menu details <slot>, pet_menu skins <slot>, pet_menu select_skin <pet> <skin> и pet_menu remove <slot>.
Если установлен UiCore, он может считывать компаньонов игрока, чтобы рисовать HUD или страницу меню.
Тексты меню, описание жетона и подпись над питомцем по умолчанию на французском (например, «Niveau», «Compagnons»). Редактируйте name, lore и noSlotMessage жетона для каждого питомца. Остальные тексты меню зафиксированы в коде.
Команды
Для каждой подкоманды требуется право typewriter.pets вместе с указанным правом. Большинство подкоманд принимают необязательный селектор игрока [target] после аргументов, чтобы действовать на кого-то другого; без него они действуют на отправителя.
| Команда | Право | Описание |
|---|---|---|
/pets open [target] | typewriter.pets.open | Открыть меню компаньонов. |
/pets activate <pet> [target] | typewriter.pets.activate | Активировать имеющегося питомца. |
/pets deactivate [target] | typewriter.pets.deactivate | Отослать активного питомца. |
/pets show [target] | typewriter.pets.show | Снова показать активного питомца. |
/pets hide [target] | typewriter.pets.hide | Скрыть активного питомца. |
/pets remove <pet> [target] | typewriter.pets.remove | Удалить питомца из меню игрока. Предмет не возвращается. |
/pets give <pet> <amount> [target] | typewriter.pets.give | Выдать от 1 до 64 предметов-жетонов. |
<pet> — это идентификатор или название записи Pet Definition. Команда /pets без аргументов в этой версии ничего не делает: используйте /pets open.
Права
Ни одно не зарегистрировано со значением по умолчанию, поэтому они есть только у операторов, пока вы не выдадите их через плагин прав.
| Право | Что даёт |
|---|---|
typewriter.pets | Дерево команд /pets. |
typewriter.pets.open | /pets open. |
typewriter.pets.activate | /pets activate. |
typewriter.pets.deactivate | /pets deactivate. |
typewriter.pets.show | /pets show. |
typewriter.pets.hide | /pets hide. |
typewriter.pets.remove | /pets remove. |
typewriter.pets.give | /pets give. |
Права из lockedSlots | Разблокируют соответствующий слот меню. Названия выбираете вы. |
Плейсхолдеры
Pets предоставляет одну запись-плейсхолдер TypeWriter, Pets Placeholder. Создайте её один раз. Тег — <typewriter_ENTRY:...>, где ENTRY — название или идентификатор этой записи в нижнем регистре, например <typewriter_pets_placeholder:active:name>, когда запись называется pets_placeholder.
| Путь аргументов | Возвращает |
|---|---|
active | Название активного питомца, пусто, если его нет. |
active:name, active:id | Название и идентификатор активного питомца. |
active:level, active:xp, active:max_level | Уровень, опыт и максимальный уровень. |
active:next_xp | Опыт, необходимый для следующего уровня, Max на максимальном уровне. |
active:damage | Урон ответного удара на текущем уровне. |
active:status | active или inactive. |
active:visibility | hidden или visible. |
active:mode | head, ground или fly. |
slot:<index>:name, id, level, xp, next_xp, max_level, damage, visibility, mode | Те же поля для питомца в этом слоте меню. |
slot:<index>:status | active, inactive или empty. |
pet:<id>:name, description, max_level, xp_per_kill, default_mode, combat, texture | Поля Pet Definition. |
pet:<id>:owned | true или false для игрока. |
pet:<id>:level, xp, next_xp, visibility, mode, damage | Копия этого питомца у игрока, пусто, если у него нет такого. |
pet:<id>:status | active, inactive или unowned. |
Записи
Записей: 6, сгенерированы из исходного кода расширения.
Действия3
- Pets Add XPGrant experience to a pet
- Pets Open MenuOpen the pet selection menu
- Pets StateChange the state of a pet
Плейсхолдеры1
- Pets PlaceholderExpose companion placeholders
Артефакты1
- Pet StoragePersist companion data
Манифесты1
- Pet DefinitionConfigure a companion pet
Устранение неполадок
Питомцы теряются после перезапуска. Не существует артефакта Pet Storage либо у действия меню нет storage. В логе видно «No pet_storage entry found. Companion data will not persist until one is created.»
Жетон сообщает, что меню заполнено. Каждый слот меню занят или заблокирован для этого игрока. Добавьте слоты в slots или выдайте право заблокированного слота. Сообщение — это noSlotMessage жетона.
«Ce familier est déjà présent dans ton menu.» У игрока может быть одна копия каждого питомца. Нельзя использовать второй жетон для того же определения.
Питомец GROUND или FLY никогда не появляется. В логе написано «Unable to summon ground pet». Задайте npc в определении или дайте хотя бы одному скину npc, критерии которого выполняются для игрока. Проверьте, что запись определения сущности существует.
Питомец не повышает уровень. Питомцу нужно требование для следующего уровня: запись levels или formula. Формула, которую нельзя вычислить, считается отсутствием требования. Проверьте, что в ней используются только числа, {level}, + - * / и скобки.
/pets ничего не выводит. Используйте /pets open. Для всех подкоманд нужно typewriter.pets плюс их собственное право, и эти права по умолчанию не выдаются.
Скин показывается как заблокированный («???»). Его criteria пока не выполняются. Проверьте факты или квесты, от которых он зависит.