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

Эти заметки описывают файлы моделей, сопутствующие файлы и имена, которые FreeMinecraftModels читает при импорте и во время работы.

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

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

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

Для отдельного .bbmodel без сопутствующих файлов:

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

Импортёр отдельных файлов оставляет оригинал в imports, поэтому следующие импорты преобразуют его повторно. Он не подбирает отдельные сопутствующие .json и .yml и не принимает отдельный .fmmodel. Храните авторские наборы моделей вместе с сопутствующими файлами в активной папке models либо используйте правильно устроенный пакет контента. Произвольная подпапка imports без pack.meta пропускается. Отклонённая перезагрузка может оставить прежний каталог активным; проверяйте консоль.

При преобразовании отдельного файла у текстур сохраняются только source, id и name; метаданные размеров и времени анимации отбрасываются. Также требуется массив textures. Если эти метаданные важны, используйте активную папку моделей или пакет, сохраняющий оригинальный файл. Сам читатель моделей времени выполнения допускает отсутствие массива текстур.

Назначение папок

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

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

В старых установках может быть папка Models с заглавной буквы. Во время работы FreeMinecraftModels предпочитает существующую models, иначе использует Models. На файловой системе без учёта регистра эти имена обозначают один каталог. На системе с учётом регистра они могут сосуществовать: общий импортёр пакетов сейчас предпочитает существующий каталог назначения Models, тогда как среда выполнения читает models. Остановите сервер, сделайте резервную копию и объедините содержимое в строчную models, чтобы импортируемые файлы не попадали за пределы активного дерева.

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

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

Нормализация ID и коллизии

Имя файла нормализуется, прежде чем стать ID модели во время выполнения и именем файла в ресурс-паке:

1. приводится к нижнему регистру
2. каждый символ вне a-z, 0-9, ., _ и - заменяется на _

Поэтому My Table.bbmodel, my table.bbmodel и my_table.bbmodel нормализуются в один и тот же ID, my_table.

Перед запуском любого преобразования FreeMinecraftModels обходит всё дерево моделей и проверяет файлы, нормализующиеся в один ID. Если все файлы с этим ID побайтно идентичны, как бывает, когда два пакета контента поставляют одну и ту же модель, FMM загружает тот, чей абсолютный путь идёт первым при сортировке, а копии пропускает без предупреждения. Если файлы различаются:

• отклоняется каждый конфликтующий файл — ни один из них не загружается, поэтому нет молчаливого «побеждает последний»
• ID модели блокируется на весь оставшийся проход загрузки
• отклонённые модели также исключаются из экспорта комплекта кастомных Bedrock-сущностей
• в консоль выводится:

[FMM Models] Rejected normalized model ID collision '<id>'. These files normalize to the same ID: <paths>. Rename the files so every normalized model ID is unique; no colliding model was loaded.

Решение всегда одно — переименовать файлы так, чтобы нормализованные ID различались. Самая безопасная привычка — с самого начала называть файлы моделей в нижнем регистре с подчёркиваниями (stone_table.bbmodel), что делает имя файла и ID времени выполнения идентичными и полностью убирает шанс неожиданной коллизии.

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

• FreeMinecraftModels читает meta.format_version из .bbmodel и ветвится по его мажорному номеру
• Отсутствующий блок meta, отсутствующий format_version или значение, которое не удаётся разобрать, — всё это откатывается к версии 4, с информационной строкой или предупреждением, называющим модель
• Отсутствующий массив textures принимается и трактуется как пустой список текстур, а не приводит к падению импортёра. Экспортёр кастомных Bedrock-сущностей затем пропускает такую модель, потому что экспорт в Bedrock требует хотя бы одной текстуры
• Имена извлечённых файлов текстур нормализуются к одному расширению .png. Исходное имя вроде body.jpg, body.PNG или body записывается и указывается как body.png
• format_version 4.x и старше: кости читаются напрямую из дерева outliner, которое несёт имена костей внутри себя
• format_version 5.x и новее: схема outliner изменилась. outliner теперь — вложенное дерево из голых строк UUID и словарей {uuid, isOpen, children} без ключа имени, тогда как отдельный плоский массив groups содержит фактические данные костей (включая name). FMM соединяет их по UUID — каждый узел outliner заменяется соответствующей записью groups, затем дочерние узлы объединяются рекурсивно, — поэтому имена костей, origin'ы и повороты разрешаются нормально
• Следствия, о которых стоит знать при ручной правке или генерации файлов .bbmodel:
  • Файл v5 без массива groups передаётся без объединения. Уже объединённый outliner может работать; необработанные безымянные узлы групп v5 могут вызвать ошибку загрузки, когда читатель скелета ожидает имя
  • UUID должны точно совпадать между outliner и groups; узел outliner без соответствующей группы сохраняется как есть, а не отбрасывается
  • Не смешивайте format_version v5 с outliner в форме v4 и наоборот — ветка выбирается по объявленной версии, а не по фактической форме
• Если журналы импорта сообщают, что формат модели несовместим с FreeMinecraftModels, рассматривайте это в первую очередь как проблему формата модели, а не вики или команды

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

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

• hitbox
  • зарезервировано для генерации хитбоксов
  • должно чётко определять хитбокс модели, а не использоваться как визуальная кость
  • должна быть костью верхнего уровня в outliner, чтобы определять столкновения во время работы. Вложенная hitbox проходит обычный разбор костей, но остаётся скрытой и не задаёт хитбокс модели
  • должна содержать ровно один куб, задающий ширину (x), глубину (z) и высоту (y). Дополнительные кубы вызывают запись has more than one value defining a hitbox! Only the first cube will be used. Пустая группа записывает has a hitbox bone but no hitbox cube! и оставляет нулевые размеры; это отличается от отсутствия хитбокса. Смещения и повороты куба не становятся смещением хитбокса: парсер использует абсолютные длины сторон и нулевое смещение модели
  • никогда не анимируется (треки анимации, нацеленные на hitbox, пропускаются), никогда не отрисовывается и исключается из экспорта геометрии Bedrock. На Bedrock модель без кости hitbox откатывается к 1.0 x 2.0
• tag_...
  • необязательный авторский якорь таблички имени. См. Положение таблички имени ниже
• h_...
  • обрабатывается как кости головы
• b_...
  • неотображаемые кости в среде Java. Для структуры используйте кости без кубов: экспорт геометрии Bedrock не фильтрует префикс b_, поэтому кубы на таких костях могут оставаться видимыми
• m_...
  • кости точек посадки. Каждая кость с этим префиксом создаёт место для игрока под управлением MountPointManager. Несколько костей m_ создают несколько мест. Менеджер выбирает первое свободное место и использует временную сущность Interaction, пока оно занято; публичный метод посадки принимает игроков, а не произвольные сущности.

Префиксы чувствительны к регистру, а имя hitbox сравнивается без его учёта. Эти имена влияют на преобразование и поведение во время работы.

Положение таблички имени

Кость tag_ теперь необязательна. FMM использует первую по алфавиту кость tag_ как якорь таблички имени. Если такой кости нет, табличка располагается над масштабированным хитбоксом, поэтому модель без теговой кости тоже может показывать имя.

Используйте кость tag_name без кубов, если запасное положение не подходит. Несколько теговых костей больше не создают несколько копий одной таблички.

API поддерживает многострочные имена, масштаб, межстрочный интервал и видимость. Строки идут сверху вниз, последняя расположена на якоре. См. Руководство по API.

Затенение кубов и излучение света

• Значение light_emission куба из Blockbench сохраняется, если это целое число от 0 до 15. Любое другое значение отбрасывается с предупреждением в консоли, оканчивающимся на with invalid light_emission. Expected an integer from 0 to 15; ignoring this value.
• Куб с отключённым затенением (shade: false) также получает shade_direction_override: "up" в сгенерированной геометрии, поэтому клиенты Minecraft 26.3 отрисовывают его без затенения, как и старые клиенты. FMM применяет то же правило к кубам в сопутствующем .json модели отображения. Значение, заданное вами вручную, сохраняется

Кубы без группы

Кубы, объявленные в верхней части outliner без содержащей их группы, приходят как «голые» строки UUID, а не как записи костей. FreeMinecraftModels присоединяет их к автогенерируемой корневой кости (freeminecraftmodels_autogenerated_root), чтобы они всё же отрисовывались. Анимации к ним обращаться не могут, поэтому всё, что вы собираетесь анимировать, помещайте внутрь настоящей группы.

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

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

• нулевых объектов Blockbench в качестве контроллеров IK
• чертежей цепей IK и решения IK во время выполнения (FABRIK)
• парсинга локаторов. Локаторы также могут служить точками привязки эффектов частиц Blockbench; см. Частицы

Нулевой объект становится контроллером IK, только если его запись .bbmodel содержит оба поля: ik_source (кость-источник) и ik_target (целевая кость или локатор). Импортёр ищет по иерархии, включая соседние элементы и нисходящие пути. Соседние элементы корневого уровня образуют цепь только из источника. lock_ik_target_rotation читается и сохраняется, но текущий решатель его не применяет.

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

• Связь источника и цели идёт по UUID, поэтому она переживает переименования — но если какого-то UUID нет в модели, в консоль пишется IK chain in model <model>: Could not find source bone with UUID ... / Could not find target with UUID ..., и эта цепь пропускается
• Если обход не находит пути от источника к цели, вы получите Could not find path from source to target, и цепь пропускается
• Поиск анимации для контроллера основан на именах, поэтому именование контроллеров должно оставаться стабильным между структурой модели и данными анимации
• IK управляют только ключевые кадры позиции. Их смещение прибавляется к положению покоя целевой кости или локатора, а не к сохранённому положению покоя контроллера. Треки вращения и масштаба не управляют IK

О том, как IK управляется покадрово, см. Анимации.

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

FreeMinecraftModels объявляет api-version: 1.21.4, поэтому 1.21.4 — это минимальная версия сервера, и современная раскладка определений моделей предметов — единственная, которую вы получите:

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

В коде всё ещё существуют устаревшие (до 1.21.4) ветки с переопределениями через кожаную конскую броню, но ни один сервер, способный загрузить текущий плагин, до них не доходит. Если вы читаете старые заметки или смотрите на старую папку вывода — вот в чём разница.

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

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

FMM читает JSON рядом с активным файлом модели, копирует его в ресурс-пак и переписывает значения без пространства имён в таблице textures. Числовые ключи текстур соответствуют индексам извлечённых текстур модели; несовпадающий ключ использует доступную текстуру, если она есть. Значения с пространством имён не меняются. Без сопутствующего JSON предмет использует вид базового материала: обычно бумаги для размещения декоративного объекта или настроенного материала для предмета в руке. Некорректный сопутствующий файл записывает Failed to process display model JSON for ..., и эта display-модель не регистрируется.

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

Задайте material в сопутствующем YAML модели, чтобы зарегистрировать предмет для удержания в руке:

isEnabled: true
material: DIAMOND_SWORD
name: "&6Flame Blade"
lore:
  - "&7A blade with a fire enchantment"
enchantments:
  - "minecraft:fire_aspect,2"

Используйте строчные ID зачарований с пространством имён. Кожаные материалы принимают суффикс окраски RGB, например LEATHER_CHESTPLATE:ff8800; см. Конфигурация. Предмет с неподдерживаемым материалом, зачарованием без пространства имён или непустым списком scripts: недоступен; консоль объясняет причину, а исходный файл сохраняется. scripts: остаётся функцией только декоративных объектов.

Другие неверные определения — например, нелогическое значение isEnabled, некорректные записи зачарований, дублирующиеся зачарования или недопустимое имя файла предмета — могут привести к отклонению нового каталога и перезагрузки. Используйте строчные имена файлов предметов только из a-z, 0-9, ., _ и -, длиной до 128 символов. Поиск авторских предметов читает .yml, но не .yaml. Зарегистрированный предмет можно получить через /fmm giveitem <item> или браузер администратора; рецепты декоративных объектов и покупки в магазине создают бумажные предметы для размещения.

Эффекты предметов теперь задаются в определениях зачарований. Жезлы и посохи используют конфигурацию магического оружия. Ни один из этих механизмов не использует прежнюю Lua-среду экипированных предметов.

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

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

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

• сохраняйте стабильные имена файлов, потому что они становятся идентификаторами среды выполнения
• сохраняйте явные имена контроллеров и анимаций, потому что поиск анимаций в Blockbench основан на именах
• используйте зарезервированные имена виртуальных костей по назначению (hitbox, tag_, h_, b_, m_). Добавляйте якорь tag_, только если запасное положение таблички над хитбоксом не подходит
• используйте строчные spawn, idle, walk, attack и death для общих состояний среды выполнения; атака и смерть по-прежнему требуют своего запуска во время работы, а другие имена — явного вызова воспроизведения (см. Анимации)
• модель, предназначенная для /fmm disguise, должна как минимум поставляться с idle и может добавлять sneak и jump, которые распознаёт только контроллер маскировки (см. Маскировки игроков)
• проверяйте импортированный вывод после /fmm reload, а не только внутри Blockbench
• проверяйте содержимое сгенерированного пака для вашей целевой версии Minecraft, особенно на 1.21.4+

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

FMM автоматически обнаруживает display-состояния лука и арбалета при генерации ресурс-пака. Каждому обязательному состоянию нужны загруженный файл модели и успешно обработанный сопутствующий display-.json; одних имён файлов недостаточно. Настройте предмет под базовым именем с подходящим материалом BOW или CROSSBOW.

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

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

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

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

plugins/FreeMinecraftModels/models/my_weapons/
  cool_bow_idle.bbmodel
  cool_bow_idle.json
  cool_bow_draw_start.bbmodel
  cool_bow_draw_start.json
  cool_bow_draw_half.bbmodel
  cool_bow_draw_half.json
  cool_bow_draw_full.bbmodel
  cool_bow_draw_full.json
  cool_bow.yml

Для арбалета добавьте также cool_bow_charged.bbmodel и cool_bow_charged.json. Конфигурация предмета — cool_bow.yml, с базовым именем без _idle.

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

• Обнаружение происходит автоматически при генерации ресурспака (при запуске или /fmm reload).
• Полный набор display-состояний получает одно общедоступное определение предмета под базовым именем, например cool_bow.json. Отдельные определения предметов _idle, натяжения и заряженного состояния удаляются; их геометрия остаётся доступна по ссылкам из базового определения
• Display-реестр предоставляет базовый ID и удаляет ID состояний. Полный набор с _charged считается арбалетом, без него — луком. Отсутствие display-состояний препятствует группировке
• Используйте базовое имя для конфигурации YML, например cool_bow.yml. Каталог предметов пропускает YML-файлы с суффиксами состояний; поиск конфигурации декоративных объектов тоже удаляет суффикс

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

У каждого обязательного состояния должен быть свой сопутствующий display-.json, например cool_bow_idle.json и cool_bow_draw_full.json. FMM соединяет их через сгенерированное базовое определение предмета. Условия и путь вывода описаны в разделе Вывод ресурс-пака.

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

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

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

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