Маскировки игроков

FreeMinecraftModels умеет маскировать любого онлайн-игрока под загруженную модель. Маскировки управляются через команды, публичный DisguiseAPI и PlayerDisguiseEntity на каждого игрока, который отвечает за невидимость и отрисовку модели для замаскированного игрока.

Команды

Команда	Право	Заметки
/fmm disguise <modelID>	freeminecraftmodels.disguise.self	Маскирует отправителя. Только для игрока
/fmm disguise <modelID> <player>	freeminecraftmodels.disguise.others	Маскирует указанного игрока. Работает из консоли
/fmm undisguise	freeminecraftmodels.disguise.self	Снимает маскировку с отправителя. Только для игрока
/fmm undisguise <player>	freeminecraftmodels.disguise.others	Снимает маскировку с указанного игрока. Работает из консоли
/fmm disguiselist	freeminecraftmodels.disguise.others	Перечисляет всех замаскированных игроков и их модели

Wildcard freeminecraftmodels.* выдаёт admin, deleteall, disguise.self и disguise.others при дефолте OP. Он также выдаёт отдельно зарегистрированное право freeminecraftmodels.bypassregionprotection.

Поведение

• Маскировка игрока, который уже замаскирован, аккуратно заменяет предыдущую маскировку — снимать её сначала не нужно.
• Замаскированный игрок делается невидимым для других, чтобы виделась только модель. Сам замаскированный игрок видит себя как обычно.
• Невидимость сохраняется и после ведра молока, и после /effect clear, и после очистки эффектов маяком, и после смерти и респавна, и после любых других действий или плагинов, которые обычно сняли бы эффект (переприменяется на следующем тике через DisguiseEffectListener).
• Хитбокс игрока не меняется. Таргетинг мобов, коллизия и PvP работают как обычно.
• Маскировки не переживают перезапуск сервера, /fmm reload или выход игрока из игры — они отслеживаются в памяти, и обработчик DisguiseListeners.onQuit снимает маскировку по PlayerQuitEvent. Смерть и смена мира не снимают маскировку.
• При /fmm reload все активные маскировки сносятся в рамках выключения плагина. После перезагрузки игроков нужно маскировать заново.

Анимации маскировки

Маскировки не используют обычный конечный автомат анимаций моделируемых сущностей. Каждая маскировка получает собственный контроллер, который каждый тик считывает состояние замаскированного игрока и выбирает анимацию по имени.

Распознаются пять зарезервированных имён анимаций, в следующем порядке приоритета (от высшего к низшему):

Приоритет	Анимация	Тип	Что запускает
1	attack	одноразовая	Игрок взмахнул рукой
2	jump	одноразовая	Игрок оторвался от земли, двигаясь вверх
3	sneak	цикл	Игрок крадётся
4	walk	цикл	Игрок сместился более чем примерно на 0.01 блока с прошлого тика
5	idle	цикл	Ничто другое не подходит

Что стоит знать о поведении:

• Учитываются только те анимации, которые действительно есть у модели. Модель без анимации sneak просто проваливается к walk или idle.

• Одноразовая анимация прерывает текущий цикл и подавляет анимации более низкого приоритета на фиксированные 20 тиков (1 секунда). Система анимаций не предоставляет колбэка завершения, поэтому это предполагаемая верхняя граница, а не реальная длина — держите анимации attack и jump в пределах секунды, если хотите чистый возврат к циклу.

• Циклы перезапускаются только тогда, когда выбранная анимация действительно меняется, поэтому ровная ходьба не начинается заново каждый тик.

• jump действительно подключён для маскировок, в отличие от (сейчас неактивного) состояния прыжка у обычных моделируемых сущностей. См. Анимации.

• Модель маскировки без анимации idle выводит предупреждение при каждой маскировке:

  Disguise model '<model>' has no 'idle' animation — disguised players using this model will freeze on the last animation frame whenever no other action is active.

  Поставляйте анимацию idle с любой моделью, которую собираетесь использовать как маскировку.

Клиенты Bedrock

Маскировки полагаются на то, что FMM отрисует пользовательскую модель. Значение по умолчанию sendCustomModelsToBedrockClientsV2: true в config.yml включает отправку моделей на Bedrock сразу из коробки; если вы установили его в false (или перенесли старый sendCustomModelsToBedrockClients: false), Bedrock-игроки не увидят ни модель, ни базового невидимого игрока — фактически они увидят пустое место там, где стоит замаскированный игрок. Даже с включённым переключателем для отрисовки модели всё равно нужен совместимый с Bedrock пайплайн ресурс-паков (Floodgate + Geyser + конвертированный ресурс-пак).

DisguiseAPI

Сторонние плагины могут управлять маскировками программно через com.magmaguy.freeminecraftmodels.api.DisguiseAPI.

import com.magmaguy.freeminecraftmodels.api.DisguiseAPI;

// Маскировка (возвращает false, если ID модели не загружен)
boolean ok = DisguiseAPI.disguise(player, "dragon");

// Снять маскировку (возвращает true, если маскировка была снята)
DisguiseAPI.undisguise(player);

// Запросы
boolean isDisguised = DisguiseAPI.isDisguised(player);
String modelID = DisguiseAPI.getDisguiseModelID(player); // null, если не замаскирован

// Неизменяемый снимок всех замаскированных игроков
Collection<Player> all = DisguiseAPI.getDisguisedPlayers();

Этот API — публичная, безопасная при рефакторингах точка входа. Плагинам следует обращаться к DisguiseAPI, а не к внутреннему DisguiseManager.

Типичные сценарии

• Ролевые и RPG-серверы: маскировка игроков под модели боссов для синематиков или квестовых скриптов.
• Проведение событий: маскировка ведущего под гигантскую пользовательскую модель.
• Маунты и транспорт: комбинируйте /fmm mount с /fmm disguise для креативных схем передвижения.
• Интеграция с EliteMobs: скрипты боссов могут маскировать игрока, инициировавшего событие, для временного эффекта трансформации.

Решение проблем

Ничего не происходит после /fmm disguise dragon. ID модели должен в точности совпадать с загруженной моделью. Проверьте имя модели через /fmm admin или автодополнение команды. Форма с указанием игрока проверяет freeminecraftmodels.disguise.others до того, как разрешает модель или игрока, и сообщает об отсутствии этого права напрямую.

Моя маскировка исчезла после /fmm reload. Это ожидаемо. Все маскировки сносятся при перезагрузке. Слушайте FmmReloadedEvent, если нужно автоматически переприменять маскировки.

Bedrock-игроки не видят маскировку. См. Клиенты Bedrock выше.

Замаскированный игрок всё ещё виден другим. Невидимость применяется как эффект на уровне пакетов. Если другой плагин принудительно снимает невидимость каждый тик (так делают некоторые античиты), это может конфликтовать с переприменением FMM. Внесите FMM в whitelist или отключите конфликтующую проверку.