Заметки по созданию моделей FreeMinecraftModels

Эта страница документирует текущие детали создания моделей, видимые в кодовой базе FreeMinecraftModels. Она намеренно консервативна: сосредоточена на контракте импорта/среды выполнения, а не на каждом предпочтении рабочего процесса Blockbench.

Исходные форматы

FreeMinecraftModels в настоящее время принимает:

• файлы .bbmodel для редактируемых исходных импортов
• файлы .fmmodel для облегчённых данных моделей, готовых к выполнению

Обычный процесс импорта:

1. поместите модель в plugins/FreeMinecraftModels/imports
2. выполните /fmm reload
3. позвольте FreeMinecraftModels импортировать модель в активный набор моделей и пересобрать сгенерированный ресурспак

Роли папок

plugins/FreeMinecraftModels/imports
plugins/FreeMinecraftModels/models
plugins/FreeMinecraftModels/models_disabled

• imports — это входная папка для ручного импорта моделей и загрузки официальных пакетов до обработки
• models содержит активный установленный контент моделей
• models_disabled содержит загруженный или установленный контент пакетов, который в данный момент отключён

Идентификаторы моделей

• Идентификаторы моделей в среде выполнения берутся из имени файла без расширения .bbmodel или .fmmodel
• Используйте стабильные, уникальные имена файлов, поскольку идентификатор — это то, к чему обращаются команды и вызовы API
• Ссылки на анимации в Blockbench основаны на именах, поэтому дублирующиеся или неясные имена внутри модели чаще вызывают проблемы, чем чистая, явная схема именования

Совместимость с Blockbench

• FreeMinecraftModels определяет версию файла Blockbench при импорте
• Текущий импортёр всё ещё содержит ветки совместимости для версий старше Blockbench v5
• Если журналы импорта сообщают, что формат модели несовместим с FreeMinecraftModels, рассматривайте это в первую очередь как проблему формата модели, а не вики или команды

Соглашения об именовании костей, значимые для среды выполнения

Текущий конвертер и конвейер скелета распознают несколько соглашений об именовании:

• hitbox
  • зарезервировано для генерации хитбоксов
  • должно чётко определять хитбокс модели, а не использоваться как визуальная кость
• tag_...
  • обрабатывается как виртуальные кости, связанные с табличкой имени
• h_...
  • обрабатывается как кости головы
• b_...
  • неотображаемые кости (скрыты в среде выполнения). Используйте их для структурных или организационных костей, которые не должны рендериться в игре.
• m_...
  • кости точек посадки. Каждая кость с этим префиксом создаёт ездовую позицию для посадки на модели. Игроки или сущности могут быть посажены на эти позиции во время выполнения. Несколько m_-костей создают несколько мест. Управляется внутренне через MountPointManager.

Это не просто стилистические соглашения; они влияют на конвертацию и поведение среды выполнения.

IK, нулевые объекты и локаторы

Текущий код подтверждает поддержку:

• нулевых объектов Blockbench в качестве контроллеров IK
• чертежей цепей IK и решения IK во время выполнения
• парсинга локаторов

Важное практическое ограничение:

• поиск контроллера IK основан на именах, поэтому именование контроллеров должно оставаться стабильным между структурой модели и данными анимации

Разделение вывода для 1.21.4+

Для Minecraft 1.21.4+ FreeMinecraftModels генерирует файлы определений моделей предметов в:

plugins/FreeMinecraftModels/output/FreeMinecraftModels/assets/freeminecraftmodels/items

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

Отображаемая модель JSON (1.21.4+)

Администраторы могут поместить файл .json рядом с файлом .bbmodel или .fmmodel с тем же базовым именем (например, table.bbmodel + table.json). Этот JSON должен быть экспортирован из Blockbench как модель «Java Block/Item» и определяет, как предмет выглядит при удержании в руке или отображении в инвентаре.

При импорте FMM копирует JSON в вывод ресурспака и автоматически переписывает голые ссылки на текстуры внутри него для указания на извлечённые текстуры модели. Если сопутствующий JSON отсутствует, предмет отображается в игре как обычная бумага.

Настройка пользовательских предметов в YML

Сопутствующий файл конфигурации .yml (с тем же базовым именем, что и модель) теперь поддерживает необязательные поля предметов. Если установлен material:, модель также доступна как пользовательский предмет для удержания в руке. Полный формат YML:

isEnabled: true
scripts:
  - my_script.lua
material: DIAMOND_SWORD      # необязательно — если задано, модель также является пользовательским предметом
name: '&b&lMy Custom Sword'  # необязательно — отображаемое имя
lore:                         # необязательно
  - '&7A custom weapon'
enchantments:                 # необязательно — формат: ENCHANTMENT_NAME,LEVEL
  - SHARPNESS,5
  - FIRE_ASPECT,2

Когда material: присутствует, модель появляется в браузере контента администратора наряду с пропсами и может быть выдана игрокам как функциональный предмет.

Заметки о Bedrock и пути рендеринга

• Поддержка Bedrock зависит от sendCustomModelsToBedrockClientsV2 (по умолчанию true; заменяет более старый ключ sendCustomModelsToBedrockClients) и окружающего пути Floodgate/Geyser/ресурспака
• Java-клиенты на поддерживаемых версиях могут использовать рендеринг через display-сущности, когда useDisplayEntitiesWhenPossible включен
• Не предполагайте, что модель, которая выглядит правильно на Java-клиенте, автоматически безопасна для вашего пути Bedrock

Практические советы по созданию моделей

• сохраняйте стабильные имена файлов, потому что они становятся идентификаторами среды выполнения
• сохраняйте явные имена контроллеров и анимаций, потому что поиск анимаций в Blockbench основан на именах
• используйте зарезервированные имена виртуальных костей осознанно (hitbox, tag_, h_, b_, m_)
• проверяйте импортированный вывод после /fmm reload, а не только внутри Blockbench
• проверяйте содержимое сгенерированного пака для вашей целевой версии Minecraft, особенно на 1.21.4+

Модели состояний лука и арбалета

FMM поддерживает автоматические состояния анимации натяжения для пользовательских предметов-луков и арбалетов. Настройка не требуется — просто назовите файлы моделей с правильными суффиксами, и FMM автоматически обнаружит набор состояний при генерации ресурспака.

Соглашение об именовании

Суффикс	Назначение	Лук	Арбалет
_idle	Предмет в руке, не натягивается и не заряжен	обязательно	обязательно
_draw_start	Начало натяжения	обязательно	обязательно
_draw_half	Натянут наполовину	обязательно	обязательно
_draw_full	Полностью натянут	обязательно	обязательно
_charged	Заряженный арбалет (стрела или ракета)	--	обязательно

Для лука нужны четыре модели (все кроме _charged). Для арбалета нужны все пять.

Пример расположения файлов

plugins/FreeMinecraftModels/imports/
  cool_bow_idle.bbmodel
  cool_bow_draw_start.bbmodel
  cool_bow_draw_half.bbmodel
  cool_bow_draw_full.bbmodel
  cool_bow.yml                  <-- конфиг использует базовое имя, а не _idle

Для арбалета добавьте пятый файл cool_bow_charged.bbmodel.

Как работает обнаружение

• Обнаружение происходит автоматически при генерации ресурспака (при запуске или /fmm reload).
• Только модель _idle получает JSON-файл определения предмета в выходном паке. Состояния натяжения и зарядки указываются как условные записи внутри этого определения.
• Только базовое имя получает файл конфигурации YML. В примере выше конфиг — это cool_bow.yml, а не cool_bow_idle.yml.

Отображаемая модель JSON

Каждая модель состояния может иметь свой сопутствующий .json файл отображаемой модели (например, cool_bow_idle.json, cool_bow_draw_full.json). FMM автоматически подключает их к сгенерированному определению предмета. Точную JSON-структуру, которая генерируется, см. в Вывод ресурспака.

За рамками данной страницы

Эта страница не пытается гарантировать:

• точные шаги в интерфейсе Blockbench
• предпочтения художественного рабочего процесса
• каждую особенность устаревших .bbmodel, описанную в более ранних локальных README-материалах

Эти детали меняются быстрее, чем проверенный контракт среды выполнения выше.