События анимации

Анимации умеют не только двигать кости. В любой момент анимации можно создать частицы, проиграть звук, изменить переменную или даже выполнить команду. В этом гайде наш Рубиновый голем будет оставлять красные искры и тяжело топать на каждом шаге, а ещё злиться, когда его сильно ранят.

Этот гайд продолжает Анимации сущностей и Контроллеры анимаций.

Файлы

RP/
  animations/
    ruby_golem.animation.json
  entity/
    ruby_golem.entity.json
  models/
    entity/
      ruby_golem.geo.json
BP/
  animations/
    ruby_golem.animation.json
  animation_controllers/
    ruby_golem.animation_controllers.json
  entities/
    ruby_golem.json

Да, в пакете поведения тоже бывают анимации. Зачем они нужны, объясняет часть 3.

Что умеет каждый пакет

Простое правило: пакет ресурсов отвечает за то, что каждый игрок видит и слышит у себя на экране. Пакет поведения отвечает за настоящие изменения в игре, общие для всех.

Часть 1: частицы

Дайте частице короткое имя

В клиентской сущности перечислены частицы, которые может использовать моб, и у каждой есть короткое имя:

"particle_effects": {
  "sparkle": "wiki:ruby_sparkle",
  "dust": "minecraft:villager_happy"
}

Справа стоит идентификатор эффекта частиц. Это может быть ванильный эффект или ваш собственный (смотрите Частицы).

Создайте её из анимации

Добавьте в анимацию particle_effects. Ключи здесь - это время в секундах, как у ключевых кадров:

"animation.ruby_golem.walk": {
  "loop": true,
  "animation_length": 1.0,
  "bones": { },
  "particle_effects": {
    "0.0": { "effect": "sparkle", "locator": "left_foot" },
    "0.5": { "effect": "sparkle", "locator": "right_foot" }
  }
}

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

Чтобы создать несколько частиц одновременно, используйте список: "0.0": [ { ... }, { ... } ].

Локаторы

Локатор - это именованная точка внутри кости модели. Их добавляют в файле геометрии:

{
  "name": "left_leg",
  "parent": "body",
  "pivot": [3, 12, 0],
  "locators": {
    "left_foot": [3, 0, 0]
  },
  "cubes": [ ]
}

Локатор находится в кости, поэтому двигается вместе с ней. Частица на left_foot следует за качающейся ногой.

Часть 2: звуки

Со звуками всё так же. Сначала короткие имена в клиентской сущности:

"sound_effects": {
  "thud": "mob.wiki.ruby_golem.step"
}

Справа стоит имя звукового события из RP/sounds/sound_definitions.json. Затем добавьте в анимацию sound_effects:

"sound_effects": {
  "0.0": { "effect": "thud" },
  "0.5": { "effect": "thud" }
}

У каждой записи звука есть effect и необязательный locator, совсем как у частиц.

Из состояния контроллера

У состояний контроллера тоже бывают particle_effects и sound_effects. Времени у них нет, ведь у состояния нет временной шкалы. Вместо этого они срабатывают, когда моб входит в состояние:

"alert": {
  "animations": ["fists_up"],
  "particle_effects": [{ "effect": "sparkle", "locator": "head" }],
  "sound_effects": [{ "effect": "roar" }],
  "transitions": [{ "idle": "!query.has_target" }]
}

Временная шкала

Кроме частиц и звуков, у анимации может быть timeline: список действий, которые выполняются в заданное время. В пакете ресурсов временная шкала выполняет Molang:

"animation.ruby_golem.blink": {
  "animation_length": 4.0,
  "loop": true,
  "timeline": {
    "0.0": "variable.eyes_closed = 0;",
    "3.8": "variable.eyes_closed = 1;"
  }
}

Каждые четыре секунды голем ненадолго закрывает глаза. Контроллер рендера может прочитать variable.eyes_closed, чтобы показать другую текстуру или спрятать кости глаз (смотрите Контроллеры рендера).

В ключе может быть одна строка или список строк: "1.0": ["variable.a = 1;", "variable.b = 2;"].

Часть 3: анимации пакета поведения

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

В пакете поведения событие может быть одним из трёх:

События сущности могут быть направлены только на самого моба, поэтому всегда пишется @s, а за ним имя события.

Шаг 1: контроллер, который следит за здоровьем

Пусть голем впадает в ярость, когда его здоровье падает ниже 20, и успокаивается, когда восстановится:

{
  "format_version": "1.10.0",
  "animation_controllers": {
    "controller.animation.ruby_golem.rage": {
      "initial_state": "calm",
      "states": {
        "calm": {
          "transitions": [
            { "enraged": "query.health < 20" }
          ]
        },
        "enraged": {
          "on_entry": [
            "/say The ruby golem is cracking!",
            "/particle minecraft:lava_particle ~ ~1 ~",
            "@s wiki:enrage"
          ],
          "on_exit": [
            "@s wiki:calm_down"
          ],
          "transitions": [
            { "calm": "query.health >= 20" }
          ]
        }
      }
    }
  }
}

Список on_entry выполняется один раз, когда голем входит в enraged. Команды выполняются от имени голема, поэтому ~ ~1 ~ означает один блок над ним.

Шаг 2: повторяющаяся анимация-таймер

Зацикленная анимация пакета поведения - удобный таймер. Эта немного лечит голема в начале каждого 10-секундного цикла:

{
  "format_version": "1.10.0",
  "animations": {
    "animation.ruby_golem.regen": {
      "loop": true,
      "animation_length": 10.0,
      "timeline": {
        "0.0": "/effect @s regeneration 3 0 true"
      }
    }
  }
}

Шаг 3: включите их в сущности

В файле сущности пакета поведения перечислите их в description и запустите через scripts.animate, точно так же, как в клиентской сущности:

{
  "format_version": "1.21.0",
  "minecraft:entity": {
    "description": {
      "identifier": "wiki:ruby_golem",
      "is_spawnable": true,
      "is_summonable": true,
      "animations": {
        "rage": "controller.animation.ruby_golem.rage",
        "regen": "animation.ruby_golem.regen"
      },
      "scripts": {
        "animate": ["rage", "regen"]
      }
    },
    "component_groups": {
      "wiki:enraged": {
        "minecraft:movement": { "value": 0.35 },
        "minecraft:attack": { "damage": 12 }
      }
    },
    "components": { },
    "events": {
      "wiki:enrage": {
        "add": { "component_groups": ["wiki:enraged"] }
      },
      "wiki:calm_down": {
        "remove": { "component_groups": ["wiki:enraged"] }
      }
    }
  }
}

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

Если что-то не работает

Больше помощи в разделе Когда что-то сломалось.

Что дальше

• Узнайте, какие команды можно запускать с временной шкалы, в разделе Команды.
• Создайте свои эффекты в разделе Частицы.
• Читайте здоровье, цели и многое другое с помощью запросов Molang.