Перейти к основному содержимому

Анимации FreeMinecraftModels

FreeMinecraftModels импортирует анимации из файлов .bbmodel и .fmmodel. Эта страница описывает зарезервированные имена, смешивание анимаций, время кадров, интерполяцию, режимы зацикливания, обратную кинематику (IK) и повороты моделей.

Правила именования костей и остальную часть контракта импорта см. в разделе Заметки по созданию моделей.

Анимации состояний​

FreeMinecraftModels привязывает эти шесть имён анимаций в нижнем регистре, а также четыре имени для плавания и езды, описанные ниже, к автоматическим состояниям времени выполнения. Всё остальное в модели — это пользовательские анимации.

Имя анимацииЗацикливаетсяКогда проигрывается
spawnнетОдин раз, при создании модели. По завершении модель переходит в walk, если её сущность движется, иначе в idle
idleдаПока у сущности нет горизонтальной скорости. Плавно переходит в walk, когда скорость по X или Z становится ненулевой
idle.longнетОдин раз, после того как модель показывала idle, не проигрывая ничего другого, в течение случайного времени от longIdleMinSeconds до longIdleMaxSeconds (по умолчанию от 15 до 30 секунд). Затем модель плавно возвращается в idle, и ожидание начинается заново
walkдаПока скорость сущности по X или Z ненулевая. Плавно переходит в idle, когда обе равны нулю
attackнетПри срабатывании. Проигрывается один раз поверх idle или walk, затем заканчивается
deathнетПри вызове removeWithDeathAnimation(). Плавно проявляется из текущей позы. По завершении модель за 20 тиков уменьшается и удаляется

Сам FMM запускает attack только у Evoker, когда клыки, призванные Evoker, появляются в пределах двух блоков от него. Остальные плагины запускают атаки через API. EliteMobs проигрывает attack.melee и attack.ranged. Любое имя, начинающееся с attack., — это атака, и проигрывается она как attack.

idle.long проигрывается один раз независимо от настройки зацикливания в Blockbench. Движение, атака или другое действие, пользовательская анимация на базовом слое и игрок, управляющий мобом как ездовым животным, начинают ожидание заново, и те же события прерывают идущую idle.long. Модель без idle.long никогда не ждёт. Для idle.long нужен FreeMinecraftModels 2.15.0 или новее; более ранние версии считают её пользовательской анимацией.

Ещё четыре базовые анимации проигрываются вместо walk и idle, пока моб плывёт или на нём едет игрок, если они есть в модели:

  • Езда. Модель на осёдланной лошади, которой управляет игрок, например питомец под всадником или маунт /fmm mount, проигрывает ride вместо walk, пока движется, и idle.ride вместо idle, пока стоит. Файл питомца может назначить другие анимации через riding.animation и riding.idleAnimation; см. Езда верхом. Плагины вызывают getAnimationComponent().setRiddenAnimation(name) и setRiddenIdleAnimation(name), где null отключает соответствующую анимацию. Модель без ride под всадником проигрывает walk, а модель без idle.ride — idle.
  • Плавание. Модель, чей моб плывёт, то есть находится в воде и не касается земли, проигрывает swim вместо walk, пока движется, и idle.swim вместо idle, пока держится на месте. Файл питомца может назначить другие анимации через swimming.animation и swimming.idleAnimation; см. Плавание. Плагины вызывают getAnimationComponent().setSwimAnimation(name) и setIdleSwimAnimation(name), где null отключает соответствующую анимацию. Модель без swim в воде проигрывает walk, а модель без idle.swim проигрывает idle, пока держится на месте. Ездовое животное, которым управляет игрок, и в воде проигрывает анимации езды.

Все четыре требуют FreeMinecraftModels 2.15.0 или новее.

Именование​

Имена анимаций пишутся в нижнем регистре. Точка отделяет общее имя от более конкретного, а подчёркивание соединяет слова внутри одной части: idle.long — разновидность idle, а attack.melee — разновидность attack. Каждая поза на месте называется idle. с добавлением имени движения, которое она приостанавливает:

ДвижениеНа месте
На сушеwalkidle, а время от времени idle.long
В водеswimidle.swim
Под всадникомrideidle.ride

Если в модели нет имени с точкой, FMM вместо него проигрывает часть имени до последней точки: attack вместо attack.melee, idle вместо idle.swim. То же касается имён, которые проигрывают скрипты и плагины: этому правилу следуют и playAnimation, и hasAnimation.

Модели, созданные раньше, использовали long_idle, attack_melee и attack_ranged. FMM находит их по новым именам, а новые имена — по старым, поэтому старые модели и старые плагины продолжают работать без изменений.

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

Правила, вытекающие из устройства конечного автомата состояний:

  • Начальное состояние — spawn, если оно есть у модели, иначе idle. Модель, где нет ни того, ни другого, показывает позу покоя, пока не начнёт идти или пока что-нибудь не запустит анимацию.
  • Используются только те анимации, которые есть в модели. Модель с walk, но без idle продолжает идти и после остановки.
  • Переключение idle/walk считывает горизонтальную скорость базовой сущности; одного вертикального движения недостаточно для ходьбы. У статических сущностей и маскировок нет базовой сущности для этой проверки, а неподвижный реквизит не движется по горизонтали. Дополнительными анимациями управляют скрипты, API или контроллер маскировок FMM.
Состояния jump нет

У обычных моделированных сущностей нет состояния прыжка. Анимация с именем jump ведёт себя как любая другая пользовательская анимация и должна запускаться по имени. Исключение — маскировки игроков: их отдельный контроллер проигрывает jump, когда игрок прыгает.

Смешивание анимаций​

FMM проигрывает анимации модели в двух слоях и каждый тик смешивает их в одну позу, на Java и на Bedrock.

СлойЧто на нём проигрывается
Базовый слойspawn, idle, idle.long, walk, анимации езды и плавания и death, а также пользовательская анимация, запущенная с blend, равным false, которая берёт на себя всю позу
Слой действийattack и все имена на attack., например attack.melee и attack.ranged, а также damaged и пользовательские анимации, запущенные с blend, равным true. Действие проигрывается поверх базового слоя, поэтому модель может атаковать на ходу

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

Плавные переходы​

ПереключениеПереход
Между idle, idle.long, walk и анимациями езды и плаванияКроссфейд за idleWalkBlendTicks, по умолчанию 5 тиков. Обе анимации продолжают проигрываться во время перехода
Любая в deathПереход от позы, которую модель показывала на предыдущем тике (с учётом действия), за deathBlendTicks, по умолчанию 4 тика
Любое другое переключениеМгновенно

Переходы ускоряются и замедляются плавно, а не идут с постоянной скоростью. Если новое переключение idle/walk прерывает переход, следующий переход начинается с позы, которую показывала модель. Действия начинаются и заканчиваются без перехода.

Override и вес смешивания​

FMM читает две настройки из свойств каждой анимации в Blockbench.

Настройка BlockbenchЭффект в FMM
Override включёнНа слое действий кости, которые анимирует эта анимация, принимают её позу и отбрасывают базовую
Override выключен (по умолчанию)На слое действий вращение и позиция анимации прибавляются к базовой позе костей, которые она анимирует, а её масштаб умножается на базовый масштаб
Blend WeightЗадаёт, насколько сильно применяется анимация, на любом слое. 1 (по умолчанию) применяет ключевые кадры как задумано автором. 0.5 применяет половину каждого вращения и позиции и сдвигает масштаб наполовину от 1 к заданному значению

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

FMM читает Blend Weight только как обычное число. Выражение Molang пишет в лог Model <model>, animation <animation> has the blend weight '<value>'. FreeMinecraftModels only reads plain numbers and uses 1. FMM не поддерживает Start Delay, Loop Delay и Anim Time Update из Blockbench. Анимация, в которой задано любое из них, пишет предупреждение в лог и проигрывается без них.

Какая анимация побеждает​

  • Пользовательские анимации, включая damaged, приоритетнее встроенных. Пока такая анимация проигрывается на любом слое, запросы атаки отбрасываются. death прерывает всё.
  • Новое действие заменяет проигрываемое действие, поэтому вторая атака перезапускает атаку, а пользовательская анимация, запущенная с blend, равным true, заменяет идущую атаку.
  • Пользовательская анимация, запущенная с blend, равным false, завершает текущее действие.
  • Пока пользовательская анимация занимает базовый слой, FMM продолжает отслеживать idle и walk под ней. Захват базового слоя прерывает идущую spawn или idle.long. Когда одноразовая пользовательская анимация заканчивается, модель сразу переходит в idle или walk, смотря что соответствует её движению. Явный запрос idle или walk немедленно завершает зацикленную пользовательскую анимацию, а после окончания одноразовой показывается он.
  • Одноразовое действие заканчивается после последнего кадра. Если базовому слою нечего показывать, например у пропса без анимаций spawn и idle, действие вместо этого удерживает последний кадр, поэтому открытая таким образом дверь остаётся открытой. Одноразовая пользовательская анимация на базовом слое тоже удерживает последний кадр, если у модели нет idle или walk, в которые можно вернуться.

У маскировок игроков другой набор​

Маскировка добавляет контроллер, который каждый тик запрашивает анимации у того же механизма воспроизведения. Его пять зарезервированных имён — attack, jump, sneak, walk, idle; они проверяются в этом порядке, пока не активен обратный отсчёт одноразовой анимации. attack проигрывается на слое действий, jump и sneak занимают базовый слой, а idle и walk выбирают встроенные состояния. Если у модели нет idle, контроллер предупреждает в консоли. Полную таблицу и ограничение длительности см. в разделе Маскировки игроков.

Пользовательские анимации​

Любую анимацию, чьё имя не входит в названия состояний выше, всё равно можно проиграть по имени:

modeledEntity.playAnimation("open", /* blend */ true, /* loop */ false);
modeledEntity.stopCurrentAnimations();
boolean exists = modeledEntity.hasAnimation("open");
context.prop:play_animation("open", true, false)
context.prop:stop_animation()
  • blend выбирает слой для пользовательской анимации. true проигрывает её на слое действий, поверх idle или walk, с учётом Override и веса смешивания из Blockbench. false отдаёт ей базовый слой, поэтому она заменяет всю позу и завершает текущее действие. См. Смешивание анимаций.
  • Запросы ставятся в очередь и применяются по порядку в начале следующего тика модели. Выполняется каждый запрос; более поздний не отменяет более ранний в очереди.
  • loop применяется к пользовательским анимациям и damaged. Встроенные имена игнорируют и blend, и loop: idle и walk всегда зацикливаются, а spawn, death и атаки проигрываются один раз. idle.long, проигранная по имени, — такая же пользовательская анимация, как любая другая.
  • Встроенные имена и имена атак сопоставляются без учёта регистра. Для остальных имён FMM сначала ищет точное имя, затем его форму в нижнем регистре, затем старое написание переименованного имени, затем общую часть имени с точкой (см. Именование). hasAnimation находит те же имена, которые проигрывает playAnimation. Чтобы встроенное состояние работало, модель должна содержать имя в нижнем регистре.
  • damaged всегда проигрывается на слое действий, что бы ни говорил blend.
  • playAnimation возвращает false для имени, которого нет у модели, и для любого запроса после запроса death. true означает, что запрос поставлен в очередь, а не что кадр проигран: атаку всё равно может отбросить идущая пользовательская анимация.
  • stopCurrentAnimations() завершает все пользовательские анимации и действия и сразу переводит модель в idle либо в позу покоя, если у неё нет idle.
  • Смерть необратима: после запроса death новые запросы воспроизведения возвращают false, запросы в очереди игнорируются, а stopCurrentAnimations() ничего не делает.

Тайминг и продолжительность​

  • Blockbench хранит длину анимации в секундах. FMM преобразует её как ceil(seconds x 20), поэтому продолжительность всегда целое число тиков, и короткие анимации округляются вверх, а не вниз.
  • Канал, у которого заданы только числа, запекается при импорте в плоский массив кадров по тикам, и воспроизведение читает один кадр на тик. Канал с ключевым кадром MoLang вместо этого вычисляется на каждом тике для каждой сущности; см. Ключевые кадры MoLang.
  • У каждой проигрываемой анимации свой счётчик тиков, поэтому базовый слой, слой действий и затухающая анимация продвигаются независимо. Зацикленные анимации индексируются как counter % duration; незацикленные фиксируются на последнем кадре.
  • Времена ключевых кадров сохраняют дробную позицию в тиках (20 x time, без округления), поэтому кадр на 0.37 с участвует в интерполяции между тиками. Кадры вычисляются на целых тиках от 0 до duration - 1. Ключевой кадр точно на объявленной границе окончания влияет на интерполяцию, но сам не попадает в выборку. Разместите конечную позу до этой границы, если отображаемый кадр должен её достигнуть.
  • Если два ключевых кадра на одном канале попадают ровно в одно и то же время, побеждает тот, который идёт позже в файле.
  • Ключевой кадр с нечисловым (не конечным) временем прерывает свою дорожку и порождает одно предупреждение Malformed animation timeline for model ... на анимацию, при этом остальные анимации модели продолжают конвертироваться.

Анимации нулевой длины допустимы​

Анимация длиной 0 (или отрицательной) считается намеренной статической позой — это распространённый приём при создании мебели и других пропсов, которым нужна именованная запись «без анимации». Она молча пропускается без предупреждения и не добавляет кадров.

Режимы зацикливания​

Настройка зацикливания Blockbench управляет экспортированной анимацией Bedrock:

Режим зацикливания BlockbenchЭкспорт для Bedrock
loop"loop": true
once"loop": false
hold"loop": "hold_on_last_frame"

В Java используется правило зацикливания встроенного состояния либо аргумент loop пользовательской анимации, а не это поле Blockbench. Поэтому воспроизведение в Java и Bedrock может отличаться, если настройки не совпадают.

Типы интерполяции​

Каждый ключевой кадр несёт один из четырёх типов интерполяции: linear, catmullrom (Smooth в Blockbench), bezier и step. Всё, что вне этого набора, не разбирается и сообщается как некорректная временная шкала.

FMM проигрывает отрезок между двумя ключевыми кадрами так, как его показывает предпросмотр Blockbench, по типам обоих кадров, проверяя их в таком порядке:

  1. Ключевой кадр step удерживает своё значение до следующего ключевого кадра.
  2. Ключевой кадр linear, за которым следует linear или step, смешивается по прямой.
  3. Если любой из двух ключевых кадров — catmullrom, отрезок идёт по кривой Катмулла-Рома через ключевой кадр перед отрезком, два ключевых кадра самого отрезка и ключевой кадр после него, так что движение плавно проходит через каждый ключевой кадр, а не останавливается в нём. Отсутствующий сосед повторяет конец самого отрезка. В анимации, у которой режим цикла Blockbench равен loop, при как минимум трёх ключевых кадрах на канале кривая продолжается через границу цикла, считая последний ключевой кадр снова первым.
  4. Иначе один из них — bezier, и отрезок следует правому манипулятору уходящего ключевого кадра и левому манипулятору приходящего, по времени и значению. У ключевого кадра, сохранённого без манипуляторов, они стоят в 0,1 секунды по обе стороны без смещения значения. Время манипулятора удерживается внутри отрезка.

До своего первого ключевого кадра канал удерживает значение этого кадра, а после последнего удерживает значение последнего.

Ключевой кадр с раздельными значениями «до» и «после» достигается со значением «до», а покидается со значением «после». На сглаженном отрезке такой ключевой кадр также обрывает кривую со своей стороны. Значение «после», которое FMM не может прочитать, игнорируется.

Эти правила применяются к запечённым каналам, к каналам MoLang в Java и к запечённым дорожкам экспорта для Bedrock. Для них нужен FreeMinecraftModels 2.15.0 или новее. Версии FreeMinecraftModels с 2.3.0 по 2.14.2 смешивали каждый отрезок только по типу приходящего ключевого кадра: catmullrom плавно замедлялся до остановки в каждом ключевом кадре, bezier использовал фиксированные контрольные точки 0.42 и 0.58 независимо от своих манипуляторов, из-за чего проигрывался почти прямо, а ключевой кадр step перескакивал к своему значению на середине ведущего в него отрезка. Раздельные значения «до» и «после» схлопывались в значение «до». Поэтому модели со сглаженными, ступенчатыми или безье-ключевыми кадрами после обновления движутся иначе, ближе к тому, что видел их автор в Blockbench.

Анимируемые каналы​

Для каждой кости запекаются три канала: вращение, позиция и масштаб. Что важно при создании модели:

  • Значения позиции делятся на 16 (пиксели Blockbench в блоки).
  • Значения вращения преобразуются в радианы.
  • Blockbench format_version 5 и новее меняет знак вращения по X и Y и позиции по X. FMM компенсирует это автоматически на основе объявленной версии формата, поэтому не исправляйте это вручную — но и не смешивайте объявление v5 с данными в форме v4.
  • Кость без ключевых кадров на канале сохраняет для этого канала своё значение покоя. Кость, которую анимация базового слоя не анимирует вообще, сбрасывается к вращению 0,0,0, смещению 0,0,0 и масштабу 1,1,1; кость, которую не анимирует действие, сохраняет базовую позу.
  • Точки данных ключевых кадров могут быть записаны в .bbmodel в виде строк. Строка, являющаяся числом, читается как это число, а пустая строка становится 1 для масштаба и 0 в остальных случаях. Любая другая строка — выражение MoLang; см. Ключевые кадры MoLang.
  • Ключевой кадр с двумя точками данных, то есть с раздельными значениями «до» и «после» из Blockbench, достигается по первому и покидается по второму. См. Типы интерполяции.

Ключевые кадры MoLang​

Значение ключевого кадра, записанное как выражение MoLang, например math.sin(query.anim_time * 360) * 10, вычисляется для каждой сущности, пока проигрывается анимация.

  • Канал, то есть вращение, позиция или масштаб одной кости либо позиция контроллера IK, у которого есть хотя бы один ключевой кадр MoLang, не запекается. Каждая сущность вычисляет его на каждом тике с той же интерполяцией и тем же преобразованием единиц, что и у запечённых каналов. Числовые ключевые кадры на этом канале сохраняют свои значения.
  • Доступны следующие запросы, в том числе с коротким префиксом q.:
ЗапросЗначение
query.anim_timeСекунды с начала этой анимации. Зацикленная анимация начинается заново с 0 на каждом цикле
query.life_timeСекунды с момента создания модели
query.modified_distance_movedБлоки, на которые сущность сместилась по горизонтали
query.is_moving1, пока сущность движется по горизонтали, иначе 0
  • Другие запросы и неизвестные переменные читаются как 0. Переменная v. сохраняет своё значение на этой сущности между вычислениями, а значение temp. (t.) живёт одно выражение.
  • Выражения используют те же операторы и математические функции, что и MoLang частиц.
  • Программа из нескольких операторов без return принимает значение своей последней строки, как её показывает предпросмотр Blockbench. v.a = 10; v.b = v.a * 3; v.b + 5 проигрывается как 35. Последняя строка, являющаяся присваиванием, равна 0. MoLang частиц сохраняет правило Bedrock, где программа без return равна 0.
  • Выражение, которое FMM не может разобрать, один раз при загрузке пишет в лог Failed to parse the keyframe expression '<expression>' in animation <animation> for model <model>: <reason>. That value plays as 0.
  • Результат, не являющийся конечным числом, проигрывается как 0.
  • Сглаженный отрезок также вычисляет ключевые кадры по обе стороны от себя, чтобы задать свою кривую. Эти вычисления не сохраняют ни одной из переменных, которые присваивают, поэтому присваивания ключевого кадра действуют только на тиках отрезков, которые он начинает или заканчивает.

Игроки Bedrock вычисляют эти каналы на своём клиенте: экспорт для Bedrock записывает ключевые кадры канала как написаны, см. Экспорт для Bedrock.

Что не анимируется​

  • Кость hitbox. Дорожки анимации, нацеленные на неё, пропускаются полностью.
  • Ключевые кадры звука и инструкций временной шкалы в дорожках эффектов Blockbench. Из дорожки эффектов FMM импортирует только ключевые кадры частиц; см. Частицы. Воспроизводите звуки из Lua-скрипта или из собственного плагина.
  • Кости, которые не удалось найти по имени. Дорожка, указывающая на отсутствующую кость, пишет в лог Failed to get bone <name> from model <model>! и пропускается.

Обратная кинематика (IK)​

Пустые объекты (null objects) Blockbench выступают контроллерами IK. FMM решает цепочки во время выполнения методом FABRIK (Forward And Backward Reaching Inverse Kinematics) с ограничением в 10 итераций и допуском 0.001.

Как это устроено:

  1. Пустой объект с ik_source (корневая кость) и ik_target (конечная кость или локатор) определяет цепочку. Поиск проверяет иерархию, а также соседние кости и потомков; соседние цели на корневом уровне дают цепочку только из исходной кости.
  2. IK управляют только ключевые кадры позиции пустого объекта. Их покадровое смещение прибавляется к позиции покоя целевой кости или локатора. Решатель не использует сохранённую позицию покоя контроллера как основу цели. Дорожки вращения и масштаба не управляют IK.
  3. Каждый тик каждая цепочка следует за самой верхней из проигрываемых анимаций, которая ею управляет: сначала действие, затем базовая анимация, затем затухающая анимация. Смещение цели этой анимации применяется, и цепочка рассчитывается. Цепочка, которой не управляет ни одна проигрываемая анимация, очищается, поэтому поза IK не переносится в анимацию, которая её не использует.
  4. lock_ik_target_rotation считывается и сохраняется, но текущий решатель его не применяет.

Цепочки, которые не удаётся разрешить, пропускаются с именованным предупреждением в консоли — точные сообщения и ограничения при создании моделей см. в разделе Заметки по созданию моделей.

Экспорт для Bedrock​

Каждая сконвертированная модель также записывает файл анимации Bedrock по пути animations/<model_id>.animation.json внутри сгенерированного бандла:

  • Идентификаторы анимаций имеют вид animation.fmm.<model_id>.a_<hex>, где <hex> — байты имени анимации в UTF-8, записанные в шестнадцатеричном виде. Поэтому два имени, различающиеся только недопустимыми для Bedrock символами, получают разные идентификаторы.
  • animation_length — это длительность в секундах, но не меньше 0.05, чтобы анимация длиной в один тик оставалась корректной.
  • Режим зацикливания отображается так, как показано в таблице Режимы зацикливания.
  • Модель без анимаций всё равно получает одну пустую запись idle, чтобы определение сущности Bedrock оставалось корректным.
  • Геометрия исключает hitbox, созданные кости именных табличек fmm_nametag_bone_* и точки посадки m_; авторские якоря tag_ остаются. Экспортёр анимаций записывает запечённые дорожки без такого же фильтра визуальных костей. Не анимируйте исключённые кости посадки в ожидании видимой геометрии.
  • Экспорт анимаций Bedrock использует запечённые кадры вращения, позиции и масштаба костей. Он не переносит в эти дорожки вращения, вычисляемые решателем IK во время работы; модели, зависящие от IK, проверяйте отдельно в Bedrock.
  • Канал кости с ключевым кадром MoLang вместо этого записывается как написан, и выражения, и числа, а клиенты Bedrock вычисляют его сами. Программа из нескольких операторов записывается с return перед последней строкой, поэтому Bedrock проигрывает то же значение, что и Java. Начиная с 2.14.2, она также получает закрывающую ;, которую требует Bedrock. Его ключевые кадры в Bedrock смешиваются линейно, какая бы интерполяция ни была задана, и записываются только их значения «до». У модели с format_version 5 или новее вращение по X и Y и позиция по X уходят с обратным знаком: число как своё отрицательное, а программа — с отрицательным значением того, что она возвращает, поэтому Bedrock проигрывает ту же позу, что и Java.
  • Экспортированная модель подвешена к кости freeminecraftmodels_lean с опорой в середине её кубов. Она показывает игрокам Bedrock наклон ориентации при движении и центрирование через четыре целочисленных свойства сущности: freeminecraftmodels:lean_x, lean_y, lean_z и body_offset. У модели, в которой больше 672 анимаций, считая сгенерированные, скрывающие кость saddle или fish, нет места для этих свойств: она не получает кость наклона и в Bedrock остаётся стоять вертикально на ногах.
  • На каждую анимацию генерируется один контроллер анимации, переключаемый свойством сущности, — именно так FMM проигрывает конкретную анимацию на клиенте Bedrock. FMM переключает контроллер по базовой анимации и действию вместе, повторяя слои Java.
  • Модель с костью по имени saddle в любом регистре получает ещё одну анимацию, freeminecraftmodels_hide_saddle, после своих собственных, а модель с костью по имени fish получает после неё freeminecraftmodels_hide_fish. Каждая из них сжимает свою кость и кости под ней до нуля и проигрывается, только пока сервер скрывает кость: седло ездового питомца, пока на него не наденут седло, и рыбу рыбачащего питомца, пока он не несёт улов домой. Для этого нужен FreeMinecraftModels 2.15.0 или новее.
  • Анимация с включённым Override записывается с "override_previous_animation": true, а вес смешивания, отличный от 1, — как "blend_weight". Базовые анимации idle, walk, spawn и death идут первыми в списке animate сущности, поэтому действия накладываются поверх них.
  • blend_transition контроллеров содержит времена переходов из Java: idle и walk плавно проявляются и затухают за idleWalkBlendTicks, death плавно проявляется за deathBlendTicks, а все остальные анимации переключаются мгновенно, включая idle.long и анимации езды и плавания. Времена записываются при генерации пака, поэтому изменение конфига доходит до игроков Bedrock после повторной генерации пака.
  • Ключевые кадры частиц становятся временной шкалой particle_effects анимации, поэтому клиенты Bedrock воспроизводят их нативно. См. Частицы.
Доступность в сборках

Для этого нужен FreeMinecraftModels 2.16.0:

  • У модели нет кости наклона при более чем 532 анимациях вместо 672, по-прежнему считая сгенерированные анимации скрытия.
  • Ключевые кадры вращения по X и Y и позиции по X проигрываются в Bedrock так же, как в Java. С 2.8.0 по 2.15.0 запечённые дорожки каждой модели и каналы MoLang модели с format_version 5 или новее уходили с зеркально отражёнными осями. Движение, равномерно качающееся вокруг нуля, выглядело так же, но поза, удерживаемая в одну сторону, в Bedrock сгибалась в другую, например локоть, согнутый назад. Игроки Bedrock увидят исправление, когда пак будет создан заново и их клиент примет новый пак.

О том, куда бандл попадает на диске, см. Вывод ресурс-пака.

Инерция поворота​

При включённом weightedTurning (по умолчанию) модель на мобе поворачивается к направлению моба с инерцией, а не мгновенно. Каждый тик скорость поворота меняется не больше чем на значение ускорения, вплоть до предельной скорости, и модель начинает замедляться заранее, чтобы остановиться ровно на новом направлении. Сам моб поворачивается и ходит как прежде. Кости модели, хитбокс, локаторы и представление на Bedrock используют направление модели.

Оба предела зависят от размера модели:

  • Размер — это кубический корень из объёма кости hitbox (ширина x глубина x высота, в блоках), умноженный на атрибут scale моба. Модель без кости hitbox вместо этого использует кубический корень из собственного ограничивающего параллелепипеда моба. Размеры меньше 0.25 считаются равными 0.25
  • Предельная скорость равна turnSpeedCap, делённому на квадратный корень из размера, и никогда не превышает 90 градусов за тик
  • Ускорение равно turnAcceleration, делённому на размер

При значениях по умолчанию turnSpeedCap: 30 и turnAcceleration: 6:

ХитбоксРазмерПредельная скорость (градусов за тик)Ускорение (градусов за тик, каждый тик)
0.5 x 0.5 x 0.50.542.412
1 x 1 x 11306
2 x 2 x 2221.23
4 x 4 x 44151.5

Прочие правила:

  • Модель поворачивается мгновенно, пока игрок едет верхом прямо на её мобе или сидит на одном из её мест m_, чтобы обзор всадника и модель оставались вместе.
  • Модель на осёдланной лошади, которой управляет игрок, например созданная через /fmm mount, смотрит туда же, куда и всадник, а её голова остаётся ровной и не следует за взглядом всадника вверх и вниз.
  • Кости головы h_ следуют за головой моба и могут опережать более медленное тело максимум на 75 градусов.
  • Умирающая модель сохраняет направление, которое у неё было. Модель с выключенной синхронизацией движения сохраняет собственное направление.
  • Статические сущности, пропсы и маскировки игроков не используют инерцию поворота.

Ориентация при движении​

Динамическая модель может не только смотреть в сторону движения, но и наклоняться по ходу движения. Ходячие существа остаются ровными, а летающие и плавающие обычно должны наклоняться. Питомцы задают это в разделе orientation своего файла питомца. Плагины вызывают DynamicEntity#setTravelOrientation(TravelOrientation). По умолчанию модели UPRIGHT.

СтильНаклон
UPRIGHTНет. Модель только смотрит туда, куда движется
TOP_FIRSTВедёт верхняя часть, как у медузы: модель наклоняется в сторону движения, при движении по горизонтали ложится на бок, а при нырянии переворачивается вверх дном
FRONT_FIRSTВедёт передняя часть, как у птицы или рыбы: модель меняет тангаж при подъёмах и пикированиях и кренится на поворотах, крен достигает 45 градусов
НастройкаПо умолчаниюЗначение
startSpeed0.6Скорость в блоках в секунду, ниже которой модель остаётся ровной, чтобы дрейф и покачивание на месте не наклоняли её
fullSpeed4.0Скорость в блоках в секунду, при которой модель полностью выравнивается по направлению движения. Между этими двумя скоростями она наклоняется частично
maxTilt180Максимальный наклон в градусах, от 0 до 180
turnSpeed180Градусов в секунду, на которые может меняться наклон
  • Наклон поворачивает всю модель вокруг середины её кубов, после направления и анимаций, поэтому за ним следуют все кости, локаторы и точки посадки.
  • Скорость берётся из движения сущности, сглаженного за несколько тиков. Перемещение более чем на 2.5 блока за один тик считается телепортацией и не наклоняет модель.
  • Модель может наклоняться иначе, пока её моб плывёт, то есть находится в воде и не касается земли. Питомцы задают это через swimming.orientation (см. Плавание), а плагины через DynamicEntity#setSwimOrientation(TravelOrientation), где null означает наклон как на суше. Во время плавания наклон следует не за сглаженной скоростью, а сразу за собственной скоростью моба, и сдерживает его только turnSpeed, поэтому нос пловца смотрит вверх, пока он поднимается, и вниз, пока он ныряет. Для этого нужен FreeMinecraftModels 2.15.0 или новее.
  • Модель плавно возвращается в вертикальное положение, когда останавливается, пока умирает, пока на ней едет игрок и пока выключена синхронизация её движения.
  • Игроки Bedrock видят наклон через экспортированную кость наклона (см. Экспорт для Bedrock). Он меняется с частотой тиков сервера без сглаживания на клиенте. После того как пак впервые перегенерирован с костью наклона, один раз перезапустите сервер, чтобы мост Bedrock зарегистрировал новые свойства сущности.

Центрирование на теле​

ModeledEntity#setCenteredOnBody(true) рисует модель так, что середина её кубов совпадает с серединой её сущности, вместо того чтобы ставить модель на ноги сущности. Летающее или плавающее существо, чья модель намного больше его скрытого тела, тогда движется, поворачивается и наклоняется вокруг этого тела. Запасная табличка имени, кликабельный бокс и хитбокс перемещаются вместе с моделью. Кости hitbox и кости табличек имени не участвуют в определении середины.

По умолчанию выключено. Питомцы включают его для видов FLYING и AQUATIC, а их ключ centerOnBody переопределяет это. Игроки Bedrock тоже видят модель центрированной через ту же кость наклона. Собственный бокс столкновений сущности Bedrock по-прежнему начинается от её ног.

Запуск анимаций из других систем​

Вызывающая сторонаТочка входа
Плагин (Java)ModeledEntity#playAnimation(String, boolean blend, boolean loop) / #stopCurrentAnimations() / #hasAnimation(String)
Lua-скрипт пропсаcontext.prop:play_animation(name, blend, loop) / context.prop:stop_animation()
Любая Lua-таблица сущностиentity.model:play_animation(name, blend, loop) / entity.model:stop_animations() (доступно, когда entity.is_modeled равно true)

Связанные интерфейсы описаны в руководстве по API для разработчиков и Lua: API реквизита.

Значения Lua по умолчанию различаются: context.prop:play_animation(name) использует blend=true, loop=true, а entity.model:play_animation(name) — false, false. Передавайте оба логических аргумента явно, когда эта разница важна.

Устранение неполадок​

Моя анимация никогда не запускается автоматически. Общая машина состояний распознаёт имена spawn, idle, idle.long, walk, swim, idle.swim, ride, idle.ride, attack и death в нижнем регистре, а все имена на attack. и damaged обрабатывает как действия. Движение управляет переходами idle/walk, плавание и управляющий всадник включают анимации плавания и езды, а idle.long ждёт тихого промежутка простоя; атака и смерть всё ещё требуют соответствующего запуска во время работы. См. Анимации состояний. Остальные имена требуют явного вызова playAnimation / play_animation, кроме дополнительных имён, выбираемых контроллером маскировок.

Моя модель вообще ничего не делает. Скорее всего, у неё нет ни анимации spawn, ни idle, поэтому она показывает позу покоя, пока не начнёт идти или пока что-нибудь не запустит анимацию. Добавьте idle.

Моя атака выглядит неправильно, пока модель идёт. При выключенном Override атака прибавляется к позе ходьбы каждой кости, которую она анимирует. Включите Override в свойствах атаки в Blockbench, чтобы эти кости принимали позу атаки, или анимируйте меньше костей. См. Override и вес смешивания.

Моя модель переключается между idle и walk слишком медленно или слишком резко. Измените idleWalkBlendTicks. Значение 0 переключает мгновенно.

Моя idle.long проигрывается слишком часто, слишком редко или вообще никогда. Измените longIdleMinSeconds и longIdleMaxSeconds. Ожидание отсчитывается, только пока модель показывает обычный idle: движение, атаки, пользовательские анимации и всадники начинают его заново. longIdleMaxSeconds: 0 отключает idle.long.

Моя сглаженная, ступенчатая или безье-анимация после обновления движется иначе. FreeMinecraftModels 2.15.0 и новее проигрывают эти ключевые кадры так, как их показывает предпросмотр Blockbench; см. Типы интерполяции. Проверьте анимацию в предпросмотре Blockbench: именно такое движение теперь проигрывает FMM.

Моя большая модель поворачивается слишком медленно. Скорость поворота падает с ростом размера; см. Инерция поворота. Увеличьте turnSpeedCap и turnAcceleration, проверьте, что кость hitbox не больше задуманного, или задайте weightedTurning: false.

В консоли ... FreeMinecraftModels does not support these ... или ... has the blend weight .... FMM проигрывает эту анимацию без Start Delay, Loop Delay и Anim Time Update из Blockbench и читает Blend Weight только как обычное число. Очистите эти поля или замените выражение Molang числом.

Анимация проигрывается, но ничего не движется. Проверьте длину анимации. Анимация нулевой длины считается статической позой и по замыслу молча пропускается.

В Bedrock останавливаются все анимации модели, включая idle, хотя Java их проигрывает. Bedrock отвергает программу MoLang с ; или присваиванием, если она не заканчивается на ;, а один отвергнутый ключевой кадр останавливает все анимации сущности. FreeMinecraftModels с 2.13.0 по 2.14.1 записывает такие программы без закрывающей ;, а 2.14.2 её добавляет. Обновитесь или на этих версиях завершайте программу ключевого кадра символом ; сами в Blockbench. Java проигрывает её так же.

Ключевой кадр MoLang застыл на 0. Проверьте консоль на Failed to parse the keyframe expression. Программа, последняя строка которой является присваиванием, равна 0; завершите её нужным значением или return. Запросы, кроме четырёх, перечисленных в разделе Ключевые кадры MoLang, читаются как 0.

Вращения зеркальны. Проверьте meta.format_version в .bbmodel. FMM меняет знак вращения по X/Y для версии формата 5 и новее; файл, который объявляет одну версию, но содержит данные другой, окажется зеркальным.

В консоли Malformed animation timeline for model .... Одну дорожку в этой анимации не удалось прочитать или интерполировать. Предупреждение выводится один раз на анимацию и называет задействованную кость или контроллер IK; остальные анимации модели всё равно конвертируются.

Звуки на моей временной шкале Blockbench ничего не делают. Ключевые кадры звука не импортируются. Запускайте звуки из Lua-скрипта или собственного плагина. Ключевые кадры частиц импортируются; если частицы не появляются, см. Частицы.