Cosmetics

3D-косметика, косметика на основе моделей предметов и скины с меню гардероба и хранилищем для каждого игрока.

Приватныеv0.0.2Меню и визуал

ТребуетсяTypeWriter0.9GUIEntityCraftEngineнеобязательноProfilesнеобязательно

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

Поддержка

Обзор

Cosmetics позволяет игрокам наряжаться и настраивать своё снаряжение. Оно охватывает два вида косметики. Косметика-сущности — это 3D-модели (шляпа, рюкзак, крылья, нимб), следующие за игроком, с необязательными частицами. Косметика предметов меняет модель настоящего предмета, который носит игрок, например части брони или меча, поэтому новый вид отображается и тогда, когда предмет держат, носят или выбрасывают. Отдельная функция скинов применяет обёртку к предмету в руке игрока.

Игроки выбирают косметику в меню гардероба с одной вкладкой на категорию. Косметика доступна, если у неё нет права, если у игрока есть её право или если её открыл администратор либо другая запись. Надетая и открытая косметика сохраняется для каждого игрока в артефактах.

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

Возможности

• Косметика-сущности — прикрепляйте к игроку любое определение сущности (отображаемый предмет, модель BetterModel…) относительно тела или головы либо с фиксацией.
• Косметика предметов — заменяет item_model и вид в носке подходящих предметов и восстанавливает их, когда косметика снимается.
• Частицы — прикрепляйте к косметике эффекты частиц.
• Категории и вкладки — группируйте косметику по категориям, одна вкладка на категорию, с фильтром владения (все, имеющиеся, отсутствующие).
• Одна на категорию — игрок носит одну косметику на категорию одновременно.
• Открытия — бесплатно, по праву, по команде или из других записей.
• Скины — обёртки для предмета в руке, выбираемые в отдельном меню и снимаемые, когда предмет выбрасывается.
• Косметика на сущностях — прикрепляйте косметику к NPC или другой сущности с помощью данных сущности.
• Плейсхолдеры и факты — показывайте количества в других плагинах и проверяйте владение в criteria.

Установка

1. Установите расширение GUI (GuiAndDialogs в сборке BTC), которое используют оба меню.
2. Для косметики-сущностей установите расширение TypeWriter Entity или другое расширение, предоставляющее определения сущностей. Косметике предметов и скинам оно не нужно.
3. По желанию: установите CraftEngine, если ваша косметика предметов нацелена на предметы CraftEngine, и расширение Profiles, если косметика должна следовать за активным профилем.
4. Положите JAR-файл Cosmetics в plugins/Typewriter/extensions/ и перезапустите сервер.
5. Предоставьте модели в вашем ресурспаке: ключи item_model для косметики предметов и скинов (Minecraft 1.21.4 или новее) и текстуры assets/<namespace>/textures/entity/equipment/ для вида надетой брони.

Быстрый старт

Создадим шляпу, которую игроки открывают с помощью права:

1. В веб-панели TypeWriter откройте страницу manifest и добавьте запись Cosmetic Category. Назовите её Hats и выберите icon.
2. Добавьте запись Cosmetic Definition. Задайте category равным ID записи категории (или её названию, если у неё нет ID), priority, menuIcon и permission (например cosmetics.hat.top_hat).
3. В model сошлитесь на определение сущности, например отображаемый предмет с моделью вашей шляпы. Задайте rotationMode равным RELATIVE_TO_HEAD и настройте offset и rotationOffset.
4. Добавьте артефакт Player Cosmetics, чтобы надетая и открытая косметика сохранялась. Оставьте artifactId для генерации веб-панелью.
5. Добавьте действие BTC Cosmetics Menu. Постройте его макет в layoutPool с пятью маркерами cosmetics_button:, описанными в разделе «Меню», и задайте baseMenuId, если используете общее шасси меню.
6. Опубликуйте. Выдайте право тестовому игроку или выполните /tw cosmetics give <player> <cosmetic entry id>, затем выполните /tw cosmetics и наденьте шляпу.

Используйте ID записи

Список открытого, список надетого, команда give и факт Has Cosmetic идентифицируют косметику по её ID записи, а не по полю cosmeticId. Поле cosmeticId показывается только как токен {cosmetic_id} в меню.

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

Определение является косметикой предмета, если у него есть itemModel или equipmentAssetId и при этом перечислены applicableCraftEngineIds или applicableItems. Любое другое определение — косметика-сущность и использует model. Косметика предметов применяется к подходящим предметам в инвентаре игрока на каждом тике обновления, а исходная модель сохраняется на предмете, чтобы её можно было восстановить.

Меню

BTC Cosmetics Menu — запись GUI с одним представлением на категорию, генерируемым из ваших записей Cosmetic Category. Категория, используемая косметикой, но никогда не объявленная, всё равно появляется как вкладка. Поместите эти маркеры в ваш макет с тегом cosmetics_button:<TYPE>:

Маркер	Где	Что делает
CATEGORY_TAB	Повторяемый	Одна вкладка на категорию. Токены: {category_id}, {category_name}, {owned}, {total}.
COSMETIC_SLOT	Повторяемый	Один слот на косметику активной вкладки, отсортированные по priority. Клик надевает или снимает, если уже надета. Отсутствующая косметика показывается, но неактивна. Токены: {cosmetic_id}, {cosmetic_name}, {category_name}, {state}.
SORT_TOGGLE	Один раз	Переключает между «все», «имеющиеся» и «отсутствующие». Токен: {current_filter}. Фильтр сбрасывается, когда игрок выходит.
CLEAR_CATEGORY	Один раз	Снимает косметику активной вкладки.
PAGE_NAV	Один раз	Левый клик — следующая страница, правый клик — предыдущая. Токены: {page}, {total_pages}, {page_indicator}. Скрыт, когда достаточно одной страницы.

categoryView — это шаблон, клонируемый для каждой категории (в его названии допустимы {category_name} и {category_id}), а categoryViewIdPrefix (по умолчанию cosmetic_) задаёт префикс id представлений. Маркера закрытия или индикатора страницы нет: закрытие обрабатывает шасси, а счётчик несёт PAGE_NAV. Тексты этих кнопок по умолчанию на французском.

Меню скинов отдельное: оно открывается действием Open Skins Menu или /tw skins, показывает скины, подходящие к предмету в основной руке игрока, и оформляется записью Skins Menu Config (skinSlots, шаблоны для открытых, активных и закрытых скинов и кнопки). Левый клик по открытому скину применяет его, а кнопки снимают скин или применяют его ко всем совместимым предметам в инвентаре. Предмет со скином при выбрасывании теряет скин.

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

Косметика и скины хранятся через два артефакта, загружаемых примерно через секунду после запуска и сохраняемых через несколько секунд после каждого изменения:

• Player Cosmetics хранит для каждого игрока открытую косметику и надетую в каждой категории.
• Player Skins хранит открытые скины и выбранный скин для каждого типа предмета.

Профили и сохранённые данные

Когда установлено расширение Profiles, надетая косметика хранится под активным профилем игрока, а не под его UUID. Косметика, сохранённая ранее под UUID, не удаляется, но больше не находится. На сервере, где уже есть реальные данные игроков, перенесите ключи, прежде чем устанавливать или обновлять расширение при наличии Profiles. Открытия всегда хранятся по UUID игрока.

Команды

Команды Cosmetics являются подкомандами команды TypeWriter, поэтому начинаются с /typewriter или /tw.

Команда	Описание
/tw cosmetics или /tw cosmetics open	Открывает меню косметики. Требует cosmetics.use.
/tw cosmetics give <player> <cosmetic>	Открывает косметику, заданную по ID записи. Требует cosmetics.admin.
/tw cosmetics remove <player> <cosmetic>	Убирает открытие. Требует cosmetics.admin.
/tw cosmetics reset <player>	Очищает косметику игрока. Требует cosmetics.admin.
/tw skins или /tw skins open	Открывает меню скинов для предмета в руке. Требует skins.use.
/tw skins give <player> <skin>	Открывает скин по его skinId. Требует skins.admin.
/tw skins remove <player> <skin>	Убирает открытие скина. Требует skins.admin.
/tw skins reset <player>	Очищает скины игрока. Требует skins.admin.

Клики в меню используют внутренние команды cosmetics ... и skins ..., обрабатываемые расширением. Вводить их вручную не предполагается.

Права

Право	Даёт доступ к
cosmetics.use	/tw cosmetics и /tw cosmetics open.
cosmetics.admin	give, remove и reset для косметики.
skins.use	/tw skins и /tw skins open.
skins.admin	give, remove и reset для скинов.
permission косметики	Право на ваш выбор, открывающее одну косметику.
permission скина	Право на ваш выбор, открывающее один скин.

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

Это теги MiniPlaceholders расширения cosmetics. Замените cat на ID или название категории, а id — на ID записи косметики.

Плейсхолдер	Возвращает
<cosmetics_total_unlocked>	Число косметики, открытой игроком.
<cosmetics_total_available>	Число определений косметики на сервере.
<cosmetics_category_unlocked:cat>	Открытая косметика в категории.
<cosmetics_category_total:cat>	Косметика в категории.
<cosmetics_is_unlocked:id>	true или false.
<cosmetics_is_active:id>	true, когда эта косметика надета.
<cosmetics_active:cat>	ID косметики, надетой в категории, пусто, если нет.

<cosmetics_category_unlocked:cat> считает только косметику, открытую командой или другими записями, а не ту, что доступна через право.

Записи

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

Действия2

• BTC Cosmetics MenuBTC Cosmetics Menu
• Open Skins Menu ActionOpens the skins menu

Факты2

• Has Cosmetic FactChecks if a player has a specific cosmetic unlocked.
• Has Skin FactVérifie si un joueur possède un skin spécifique.

Данные сущностей1

• Cosmetic Entity DataAttach cosmetics to an entity definition

Артефакты2

• Player Cosmetics ArtifactStores player unlocked cosmetics
• Player Skins ArtifactStores player selected skins

Манифесты4

• Cosmetic CategoryDéfinition d'une catégorie de cosmétiques (ex: Chapeaux, Capes)
• Cosmetic DefinitionDefine a 3D Cosmetic
• Skin DefinitionDéfinition d'une catégorie de skins (wraps) pour les items
• Skins Menu ConfigConfiguration du menu des skins

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

Меню сообщает «Aucun menu de cosmétiques n'est configuré». Не опубликована ни одна запись BTC Cosmetics Menu. /tw cosmetics открывает первую найденную.

Вкладка категории пуста или косметика отсутствует. category у косметики должна совпадать с ID записи категории (или названием, если у неё нет ID) без учёта регистра. Название, не совпадающее ни с одной записью категории, всё равно создаёт собственную вкладку.

Модель никогда не появляется. Косметике-сущности нужен model, ссылающийся на определение сущности. Определение с itemModel, но без applicableItems или applicableCraftEngineIds не является косметикой предмета и переходит на путь сущности. Для косметики предмета ключ itemModel должен быть корректным ключом с пространством имён (namespace:path); неверный ключ один раз записывается в лог как «Invalid itemModel».

Модель предмета меняется в инвентаре, но не на теле. itemModel меняет вид предмета только в руке и в инвентаре. Для брони также задайте equipmentAssetId — ресурс экипировки материала (например armors:enderite) без названия части. Он применяется, только когда надетый предмет уже несёт компонент equippable.

Предмет CraftEngine не получает косметику. Используйте applicableCraftEngineIds с id CraftEngine (например armors:enderite_helmet). Предмет CraftEngine распознаётся по id, а не по материалу, поэтому applicableItems его не сопоставит.

Надетая косметика или открытия теряются. Добавьте артефакты на опубликованную страницу. Лог сообщает об отсутствующем артефакте или «has no generated artifact id», и без них ничего не сохраняется. Если расширение Profiles было установлено недавно, см. предупреждение выше.

Другие игроки не видят мою косметику. Косметика-сущности — это фальшивые сущности. Если в логе написано «Viewer method ... unavailable ... owner-only fallback active», используемое расширение Entity не допускает дополнительных зрителей, и косметику видит только владелец.

/tw skins сообщает, что для этого предмета нет скина. Предмет в руке должен совпадать с предметом из applicableItems записи Skin Definition, в которой указан хотя бы один скин, и должна быть опубликована запись меню скинов. Тексты сообщений берутся из записи Skins Menu Config.

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

• GUI — макеты и шасси меню.
• Profiles — косметика может следовать за активным профилем.
• BetterModel — 3D-модели, пригодные как косметика-сущности.