FAQ по FreeMinecraftModels

Если вашего вопроса нет в списке, посмотрите боковую панель — возможно, ему посвящена отдельная страница в вики!

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

Как установить и использовать FreeMinecraftModels?

Подробнее

Установка:

1. Скачайте FreeMinecraftModels.jar и поместите в папку plugins
2. Перезапустите сервер, чтобы плагин создал свои папки
3. Выполните /fmm setup для меню первичной настройки / управления контентом
4. Если используете официальные паки контента, привяжите Nightbreak командой /nightbreaklogin <token>
5. Используйте /fmm setup или /fmm downloadall для официального контента, управляемого Nightbreak
6. Для ручного контента положите файлы .bbmodel в ~/plugins/FreeMinecraftModels/imports/ и выполните /fmm reload
7. Найдите сгенерированный ресурс-пак в ~/plugins/FreeMinecraftModels/output/FreeMinecraftModels.zip

Раздача ресурс-пака:

Выберите один из способов:

• Вариант A (Рекомендуется): установите Resource Pack Manager для автоматической раздачи
• Вариант B: настройте вручную через server.properties или хостинг

Спавн моделей:

• /fmm spawn static <id> - заспавнить временную декоративную модель
• /fmm spawn dynamic <id> - заспавнить модель, привязанную к сущности
• /fmm spawn prop <id> - заспавнить постоянную модель в мире

Управление:

• /fmm - открыть меню крафтящихся предметов (требует freeminecraftmodels.menu)
• /fmm setup - открыть меню управления контентом / первичной настройки
• /fmm recommendedplugins - просмотреть плагины-компаньоны, хорошо сочетающиеся с FMM
• /fmm downloadall - скачать последнее обновление плагина плюс весь доступный официальный контент
• /fmm downloadallcontent - скачать весь доступный официальный контент (только контент)
• /fmm updatecontent - обновить устаревший официальный контент
• /fmm downloadpluginupdate - скачать только последнее обновление jar плагина
• /fmm reload - перезагрузить плагин и преобразовать новые модели
• /fmm version - показать версию плагина
• /fmm stats - показать статистику по числу сущностей

Возможности для игроков:

• /fmm disguise <modelID> [player] - превратить свою (или целевого игрока) внешность в пользовательскую модель
• /fmm undisguise [player] - снять маскировку с игрока
• /fmm disguiselist - показать всех замаскированных сейчас игроков
• /fmm itemify <model> <material> - создать размещаемый предмет, который спавнит указанную модель
• /fmm craftify <modelID> - открыть интерактивный конструктор рецептов для создания рецепта крафта реквизита
• /fmm shop - открыть опциональный магазин мебели на базе Vault (только когда включён в shop_config.yml)
• /fmm mount <modelID> - заспавнить ездовую лошадь, замаскированную под пользовательскую модель (экспериментально)

Отладка:

• /fmm hitbox visualize [duration] - визуализировать хитбоксы моделей частицами (длительность в тиках, по умолчанию 100)
• /fmm location - сообщить о зарегистрированных провайдерах защиты/подземелий и проверить их в вашей текущей позиции
• /fmm debug bedrock [on|off] - переключить подробный поток логов [FMM-BedrockDebug] для диагностики пайплайна отображения Bedrock. Не является ключом конфига — сбрасывается в OFF при каждой перезагрузке

Администрирование:

• /fmm deleteall [radius] - удалить все загруженные моделированные сущности и реквизиты (используйте с осторожностью — без подтверждения). Необязательный [radius] (только для игрока) ограничивает удаление указанным числом блоков

Права:

• freeminecraftmodels.* (по умолчанию: OP) - Wildcard, выдающий freeminecraftmodels.admin, freeminecraftmodels.deleteall, freeminecraftmodels.disguise.self и freeminecraftmodels.disguise.others. Также является буквальным правом, требуемым для /fmm reload, /fmm stats, /fmm spawn, /fmm itemify, /fmm craftify, /fmm mount, /fmm hitbox visualize, /fmm debug bedrock, /fmm location, /fmm setup, /fmm recommendedplugins, /fmm downloadall, /fmm downloadallcontent, /fmm updatecontent и /fmm downloadpluginupdate
• freeminecraftmodels.admin (по умолчанию: OP) - /fmm admin (админский браузер контента) и /fmm giveitem
• freeminecraftmodels.disguise.self (по умолчанию: OP) - даёт игроку маскировать/снимать маскировку только с себя
• freeminecraftmodels.disguise.others (по умолчанию: OP) - разрешает целевую маскировку/снятие и /fmm disguiselist
• freeminecraftmodels.deleteall (по умолчанию: OP) - требуется для /fmm deleteall (потомок wildcard)
• freeminecraftmodels.bypassregionprotection (по умолчанию: OP) - размещение/взаимодействие с реквизитами внутри регионов WorldGuard или приватов GriefPrevention, даже когда включён preventPropPlacementInProtectedRegions
• freeminecraftmodels.menu (по умолчанию: true) - позволяет всем игрокам открывать браузер крафтящихся предметов через /fmm
• freeminecraftmodels.shop (по умолчанию: true) - позволяет всем игрокам открывать /fmm shop (при этом магазин должен быть включён)

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

Возможности и ограничения моделей

Какие ограничения на размер и поворот моделей?

Подробнее

Ограничения по размеру:

• Максимальный bounding box на кость: 192×192×192 пикселя модели (12×12×12 игровых блоков) — измеряется по всем кубам в пределах одной кости
• FreeMinecraftModels использует внутреннее масштабирование ×4 и сдвигает начало модели, чтобы уложиться в диапазон ресурс-паков Minecraft -16..+32
• Если кость превышает лимит, FMM пишет предупреждение в консоль; уменьшите кубы, придвиньте их ближе друг к другу или разнесите по нескольким костям
• Модели целиком могут быть и больше этого размера — ограничение действует только на отдельную кость

Ограничения поворота кубов:

• Допустимые углы: 0°, ±22.5°, ±45° и кратные 22.5° (начиная с v2.3.0)
• Поворот только по одной оси
• Пример: [22.5, 0, 0] работает, а [22.5, 0, 45] поворачивается лишь частично
• Другие углы будут отображаться некорректно

Поворот костей:

• Кости поддерживают любой угол поворота
• Избегайте дефолтных положений покоя 90°, -90°, 180°, -180° (могут давать неожиданное поведение)
• Поддерживается поворот по нескольким осям
• Каждая кость создаёт отдельную сущность (учитывайте производительность)

Замечание о производительности:

Держите количество костей как можно меньше. Каждая кость спавнит отдельную сущность Minecraft, что может влиять на производительность сервера при масштабировании.

Какие анимации поддерживаются?

Подробнее

FreeMinecraftModels поддерживает следующие дефолтные анимации состояний (объявлены в перечислении AnimationStateType):

Стандартные анимации:

• spawn
• idle
• walk
• jump
• attack
• death
• custom (универсальная для одноразовых анимаций, запускаемых через API или Lua)

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

• Создавайте анимации в BlockBench с именами в нижнем регистре, как выше, чтобы FMM автоматически привязал их к соответствующему состоянию
• Плагин читает ключевые кадры анимации из файлов .bbmodel
• Анимации запускаются автоматически в зависимости от состояния сущности
• Разработчики могут запускать анимации программно через playAnimation(animationName, blend, loop) на ModeledEntity или через context.prop:play_animation(name, blend, loop) из Lua

Особый случай:

Сущности Evoker обнаруживают рядом клыки Evoker (Evoker Fangs), чтобы автоматически запускать анимации атаки.

Что такое виртуальные кости и как они работают?

Подробнее

Виртуальные кости — это специальные кости с зарезервированными именами, добавляющие функциональность вашим моделям:

Кости хитбоксов:

• Имя: hitbox
• Создаёт зоны взаимодействия и боксы коллизий
• Задаёт границы сущности при совпадающих значениях x/z

Кости тегов-имён:

• Префикс: tag_
• Отображает текст над моделями
• Используется для именования сущностей

Кости поворота головы:

• Префикс: h_
• Поворачивается в зависимости от положения головы игрока/сущности
• Автоматически отслеживает движение головы

Использование:

Создайте кость в BlockBench с одним из этих специальных имён, и плагин автоматически применит соответствующую функциональность.

FAQ по устранению неполадок

Вместо пользовательских моделей я вижу только лошадиную броню.

Подробнее

Если вместо пользовательских моделей в игре вы видите только лошадиную броню, скорее всего, проблема в том, что вы неправильно объединили ресурс-пак FMM с вашим уже существующим ресурс-паком.

MagmaGuy разработал плагин под названием Resource Pack Manager (RSPM), который может автоматически объединять ресурс-паки за вас. Скачать его можно со Spigot здесь.

Просто положите .jar-файл RSPM в папку plugins, и RSPM сделает всё за вас. Он объединит все ресурс-паки, автоматически их захостит и раздаст игрокам при входе на ваш сервер.

Почему я не вижу свою модель после добавления файла .bbmodel?

Подробнее

Если ваша модель не появляется, проверьте эти распространённые проблемы:

1. Забыли перезагрузить

Выполните /fmm reload после размещения файлов .bbmodel в папке imports. Это преобразует модели и генерирует ресурс-пак.

2. Ресурс-пак не применён

У игроков должен быть активен ресурс-пак FMM, чтобы видеть модели.

• Проверьте ~/plugins/FreeMinecraftModels/output/FreeMinecraftModels.zip на наличие сгенерированного пака
• Установите Resource Pack Manager для автоматической раздачи
• ИЛИ раздайте вручную через server.properties или хостинг

3. Неправильное расположение файла

Файлы .bbmodel для ручного импорта должны лежать в: ~/plugins/FreeMinecraftModels/imports/

Если вместо этого вы используете официальные паки контента, используйте /fmm setup или /fmm downloadall, а не кидайте файлы вручную.

4. В модели есть ошибки

Проверьте логи консоли на сообщения об ошибках во время /fmm reload. Распространённые проблемы — неподдерживаемые повороты, слишком большие модели или проблемы с текстурами.

5. Проблема с объединением ресурс-паков

Если вы видите лошадиную броню вместо моделей, ресурс-паки были объединены неправильно. Используйте Resource Pack Manager (RSPM) для автоматического объединения.

ViaVersion может приводить к некорректному отображению ресурс-паков.

Подробнее

ViaVersion может вызывать проблемы с ресурс-паками, особенно при запуске сервера на версии ниже 1.21.4. В Minecraft, начиная с 1.21.4, изменилась обработка ресурс-паков. Если вы запускаете сервер на версии вроде 1.21.3 и используете ViaVersion, чтобы дать клиентам 1.21.4 подключаться, такие клиенты могут испытывать проблемы с отображением определённого содержимого ресурс-пака, например пользовательских моделей из FMM (FreeMinecraftModels).

Это происходит потому, что система ресурс-паков в Minecraft изменилась с обновлением 1.21.4.

Примечание: Это ограничение Minecraft и ViaVersion, а не специфика FreeMinecraftModels. Трансляция протокола ViaVersion может не полностью поддерживать изменения ресурс-паков при работе на версиях сервера ниже 1.21.4.

Чтобы это решить, рассмотрите обновление сервера до 1.21.4 или выше, так как это обеспечит лучшую совместимость с современными возможностями ресурс-паков, включая пользовательские модели FMM.

Почему мои модели вызывают лаги или проблемы с производительностью?

Подробнее

Каждая кость в вашей модели BlockBench создаёт отдельную сущность в Minecraft. Модели с большим числом костей могут влиять на производительность сервера.

Советы по оптимизации:

• Минимизируйте количество костей в моделях
• Ограничьте число заспавненных моделей
• По возможности используйте статические модели вместо динамических, когда анимации не нужны
• Избегайте спавна множества моделей с большим числом костей рядом друг с другом

Техническое объяснение:

FreeMinecraftModels отрисовывает каждую кость как отдельную сущность Minecraft. Модель с 50 костями спавнит 50 сущностей. При масштабировании это влияет на производительность.

Лучшие практики:

• Проектируйте модели с меньшим числом костей
• Тестируйте производительность с реалистичным числом спавнов
• Следите за TPS сервера при добавлении новых моделей

Продвинутые возможности

Нужен ли мне Resource Pack Manager (RSPM)?

Подробнее

Resource Pack Manager (RSPM) — необязателен, но крайне рекомендуется.

Что делает RSPM:

• Автоматически объединяет ресурс-паки от нескольких плагинов
• Хостит ресурс-паки (внешний хостинг не нужен)
• Автоматически раздаёт паки игрокам при входе
• Избавляет от ручной настройки ресурс-пака

Без RSPM:

Вам придётся вручную:

• Объединять ресурс-пак FMM с любыми существующими ресурс-паками сервера
• Хостить объединённый пак на внешнем сервисе или через server.properties
• Настраивать сервер на отправку пака игрокам
• Обновлять пак каждый раз при добавлении новых моделей

Зачем использовать RSPM:

Большинство проблем «лошадиная броня вместо моделей» вызвано неправильным объединением ресурс-паков. RSPM делает это автоматически.

Скачать RSPM: https://www.spigotmc.org/resources/resource-pack-manager.118574/

Разработан MagmaGuy, тем же автором, что и FreeMinecraftModels.

Можно ли использовать FreeMinecraftModels в своём собственном плагине?

Подробнее

Да, FreeMinecraftModels предоставляет API для разработчиков.

Интеграция через Maven/Gradle:

Репозиторий: https://repo.magmaguy.com/releases

Артефакт:

• GroupId: com.magmaguy
• ArtifactId: FreeMinecraftModels
• Scope: provided (должен быть установлен на сервере, не используйте shade)

Основные классы API:

• ModeledEntity (базовый класс)
• StaticEntity
• DynamicEntity
• PropEntity

Пример использования:

StaticEntity staticEntity = StaticEntity.create(id, location);
if (staticEntity == null) {
    Bukkit.getLogger().warning("Failed to create model");
    return;
}
staticEntity.setRightClickCallback(...);
staticEntity.remove();

Важно:

Не используйте shade для FreeMinecraftModels в своём плагине. Он должен быть установлен на сервере отдельно.

Подробную документацию по API см. в официальном README.

Как замаскировать игрока под пользовательскую модель?

Подробнее

Команда /fmm disguise превращает внешность игрока в любую пользовательскую модель.

Команды:

/fmm disguise <modelID> [player]
/fmm undisguise [player]
/fmm disguiselist

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

• Делает игрока невидимым для других игроков
• Накладывает пользовательскую модель на позицию игрока
• Модель следует за движениями игрока
• Отлично подходит для ролевых серверов или особых событий

Примеры:

/fmm disguise dragon              # Замаскировать себя
/fmm disguise dragon Steve         # Замаскировать другого игрока
/fmm undisguise Steve              # Снять маскировку со Steve
/fmm disguiselist                  # Список всех замаскированных сейчас

Требования:

• Цель — сам отправитель: freeminecraftmodels.disguise.self (по умолчанию: OP)
• Цель — другой игрок и /fmm disguiselist: freeminecraftmodels.disguise.others (по умолчанию: OP)
• Консоль может запускать целевую форму, если указано имя игрока
• modelID должен быть валидной преобразованной моделью в вашей папке моделей
• Сторонние плагины могут управлять маскировкой через публичный DisguiseAPI

Заметки:

• Хитбокс игрока остаётся неизменным (тот же бокс коллизий)
• Другие игроки видят пользовательскую модель вместо скина вашего игрока
• Повторная маскировка при уже наложенной аккуратно заменяет предыдущую
• Невидимость сохраняется и после ведра молока, и после других взаимодействий, очищающих эффекты, пока с игрока не снимут маскировку

Как создать размещаемые предметы-модели?

Подробнее

Команда /fmm itemify создаёт особые предметы, которые игроки могут использовать для размещения моделей в мире.

Команда:

/fmm itemify <model> <material>

Параметры:

• model - любой валидный ID модели из вашей папки моделей
• material - любой материал Minecraft (STICK, PAPER, DIAMOND и т. д.)

Пример:

/fmm itemify lamp_post STICK

Что создаётся:

• Пользовательский предмет с отформатированным золотисто-декорированным отображаемым именем (например, «✦ Wolf ✦»)
• Описательный lore, объясняющий предмет
• Предмет добавляется прямо в ваш инвентарь
• Кликните правой кнопкой, чтобы разместить модель как реквизит

Сценарии использования:

• Выдать игрокам предметы для украшения построек
• Создать пользовательские «яйца спавна» для мебели
• Раздавать модели без выдачи прав на строительство
• Наборы для творческого строительства

Требования:

• Право: freeminecraftmodels.*
• Игрок должен быть в игре (не консоль)

Как отлаживать хитбоксы моделей?

Подробнее

Команда /fmm hitbox visualize визуализирует хитбоксы моделей с помощью частиц.

Команда:

/fmm hitbox visualize [duration]

Параметры:

• duration (необязательно) - как долго показывать хитбоксы в тиках (по умолчанию: 100, максимум: 1200)
• 20 тиков = 1 секунда

Примеры:

/fmm hitbox visualize          # Показать на 5 секунд
/fmm hitbox visualize 200      # Показать на 10 секунд

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

• Ищет модели в пределах 10 блоков от вас
• Отображает границы ориентированного bounding box (OBB) частицами
• Показывает и модель, и её границы коллизий
• Полезно для проверки размера и поворота хитбокса

Когда использовать:

• Проверка соответствия хитбоксов визуальным моделям
• Отладка проблем со взаимодействием
• Проверка поворотов хитбоксов
• Устранение неполадок с определением кликов

Требования:

• Право: freeminecraftmodels.*

Примечание: Хитбоксы в FMM поворачиваются вместе с моделью, в отличие от стандартных AABB Minecraft.

Можно ли создавать ездовые пользовательские модели?

Подробнее

Да, используйте команду /fmm mount, чтобы создавать ездовые пользовательские модели (экспериментальная функция).

Команда:

/fmm mount <modelID>

Что она делает:

• Спавнит лошадь в вашей позиции
• Маскирует лошадь под вашу пользовательскую модель
• Автоматически приручает лошадь и добавляет седло
• Тут же сажает вас верхом на лошадь

Пример:

/fmm mount dragon

Требования:

• Право: freeminecraftmodels.*
• Валидный ID модели

Важные заметки:

• Эта функция помечена как экспериментальная
• Скорость и поведение движения соответствуют обычной лошади
• Хитбокс лошади остаётся неизменным
• Лучше всего работает с моделями, спроектированными под маунтов

Сценарии использования:

• Пользовательские маунты для ролевых серверов
• Особый транспорт для VIP-игроков
• Уникальные ездовые существа для приключенческих карт

Что такое кости точек посадки?

Подробнее

Точки посадки позволяют задавать ездовые позиции прямо на вашей модели с помощью специально названных костей.

Как создать точки посадки:

В Blockbench назовите любую кость с префиксом m_ (например, m_seat, m_back). Каждая кость m_ становится позицией для посадки на модели, куда можно посадить игрока или сущность.

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

• Позиция посадки следует за расположением кости, включая анимации
• Несколько костей m_ создают несколько мест
• Игроков/сущностей можно сажать на эти позиции через API или Lua-скрипты

Тестирование:

Используйте /fmm mount <modelID>, чтобы быстро протестировать точки посадки на модели.

Сценарии использования:

• Многоместные транспортные средства (лодки, кареты)
• Ездовые существа с конкретными местами посадки
• Питомцы или компаньоны на плече

Пользовательские предметы

Что такое пользовательские предметы?

Подробнее

Пользовательские предметы — это модели, у которых в сопутствующем файле конфигурации YML задано поле material:, что превращает их в держимые, экипируемые предметы с поддержкой Lua-скриптинга.

Ключевые отличия от предметов размещения реквизита:

• Пользовательские предметы используют PDC-ключ fmm_item_id (PersistentDataContainer)
• Предметы размещения реквизита (из /fmm itemify) используют PDC-ключ model_id
• Пользовательские предметы поддерживают 22 специфичных для предметов Lua-хука (equip, attack, consume и т. д.)
• У пользовательских предметов могут быть зачарования, пользовательские имена и lore, заданные в их конфигурации YML

Как создать пользовательский предмет:

1. Создайте модель .bbmodel в Blockbench
2. Создайте сопутствующий файл YML с тем же базовым именем (например, magic_sword.yml рядом с magic_sword.bbmodel)
3. Задайте поле material: в YML на любой валидный материал Minecraft (например, material: DIAMOND_SWORD)
4. По желанию задайте поля name:, lore: и enchantments:
5. По желанию создайте Lua-скрипт в plugins/FreeMinecraftModels/scripts/ и сошлитесь на него через поле scripts:

Пример YML:

isEnabled: true
material: DIAMOND_SWORD
name: "&6Flame Blade"
lore:
  - "&7A legendary weapon"
  - "&cBurns enemies on hit"
enchantments:
  - "FIRE_ASPECT,2"
scripts:
  - flame_blade.lua

Как получить пользовательский предмет:

• /fmm giveitem <id> (требует право freeminecraftmodels.admin)
• Через админское меню (/fmm admin)

Меню

Какие меню предоставляет FMM?

Подробнее

FreeMinecraftModels предоставляет два внутриигровых меню для просмотра и управления контентом.

Меню игрока — /fmm

• Право: freeminecraftmodels.menu (по умолчанию: true, доступно всем игрокам)
• Показывает только предметы, для которых заданы рецепты крафта
• Кликните по предмету, чтобы увидеть детальный вид с пространственным превью сетки крафта 3×3
• Позволяет игрокам узнавать и понимать, как крафтить пользовательские предметы

Админское меню — /fmm admin

• Право: freeminecraftmodels.admin (по умолчанию: OP)
• Полный браузер контента, показывающий:
  • установленные пакеты
  • неупакованные папки моделей
  • модели корневого уровня
  • пользовательские предметы (модели с заданным material:)
• Позволяет администраторам выдавать предметы, просматривать модели и управлять контентом

Display-модели

Что такое display-модели?

Подробнее

Display-модели позволяют пользовательским предметам показывать 3D-модель в инвентаре и руке игрока вместо стандартного вида материала.

Как настроить display-модель:

1. В Blockbench используйте File > Export > Java Block/Item, чтобы экспортировать файл модели .json
2. Поместите файл .json рядом с файлом .bbmodel с тем же базовым именем (например, magic_sword.json рядом с magic_sword.bbmodel)
3. Выполните /fmm reload

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

• На Minecraft 1.21.4+ предмет будет отображаться с пользовательской 3D-моделью, когда его держат или смотрят в инвентаре
• Голые ссылки на текстуры в JSON автоматически переписываются в пути пространства имён FMM
• Если файла .json нет, предмет откатывается на обычный вид материала
• Старые версии сервера молча игнорируют display-модели

Требования:

• Сервер на Minecraft 1.21.4 или новее
• Валидный экспорт Blockbench «Java Block/Item» (.json), помещённый рядом с файлом модели