Заметки по созданию моделей 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_... или mount_...
  • кости точек посадки. Каждая кость с этим префиксом создаёт позицию для посадки на модели. Игроки или сущности могут быть посажены на эти позиции во время выполнения. Несколько костей посадки создают несколько мест. Управляется внутренне через 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 зависит от sendCustomModelsToBedrockClients и окружающего пути Floodgate/Geyser/ресурспака
• Java-клиенты на поддерживаемых версиях могут использовать рендеринг через display-сущности, когда useDisplayEntitiesWhenPossible включен
• Не предполагайте, что модель, которая выглядит правильно на Java-клиенте, автоматически безопасна для вашего пути Bedrock

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

• сохраняйте стабильные имена файлов, потому что они становятся идентификаторами среды выполнения
• сохраняйте явные имена контроллеров и анимаций, потому что поиск анимаций в Blockbench основан на именах
• используйте зарезервированные имена виртуальных костей осознанно (hitbox, tag_, h_, b_, m_, mount_)
• проверяйте импортированный вывод после /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-материалах

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