Эффекты и действия

# Эффекты и действия

effects и actions решают разные задачи.

effects описывает состояние, которое должно сохраняться, пока талант активен.
actions выполняется ОДИН РАЗ после покупки ранга.

Постоянные эффекты

Эффект узла включается после покупки первого ранга. Эффекты купленных объектов в ranks складываются.

effects:
  - permission: varryal.mining
  - recipe: minecraft:crafting_table
  - tag: varryal-miner
  - modifier:
      key: mining-speed
      operation: add
      value: 0.1
      per-rank: true

Эффект	Что делает
`permission`	Выдаёт право через общий механизм прав.
`recipe`	Открывает рецепт.
`tag`	Поддерживает активный тег таланта.
`modifier`	Добавляет вычисляемое числовое значение.
`external`	Передаёт постоянное состояние зарегистрированному внешнему обработчику.

Модификаторы

Доступные операции: set, add, multiply, min и max.

Для одного ключа последний активный set задаёт основу. Затем применяются add, multiply, min и max. Порядок: категория, узел, ранг.

per-rank: true умножает значение эффекта узла на текущий ранг.

Внешний постоянный эффект

effects:
  - external:
      provider: custom-stats
      payload: mining-speed

Провайдер должен быть зарегистрирован другим плагином.

Одноразовые действия

actions:
  - command: "minecraft:give {playerName} minecraft:diamond 1"
  - event:
      id: talent.mining.rank
      payload: ""
  - external:
      provider: quest-system
      payload: mining-unlocked

Тип действия	Когда использовать
`command`	Нужно выполнить Minecraft-команду от консоли или игрока.
`event`	Другой плагин должен сам отреагировать на покупку таланта.
`external`	Другой плагин зарегистрировал специальный обработчик через VarryalAPI.

Команду можно выполнить от консоли или игрока:

actions:
  - command:
      value: "say Talent purchased!"
      executor: console # или player

Действие на уровне узла выполняется при покупке каждого ранга. Действие внутри ranks выполняется только для своего ранга.

event не выполняет Minecraft-команду и сам по себе не выдаёт игроку награду. Он отправляет серверное Bukkit-событие, которое может обработать другой плагин.

id – имя сигнала. В примере talent.mining.rank может означать «игрок купил ранг таланта добычи». payload – произвольная строка с дополнительными данными для плагина-обработчика; она может быть пустой.

Слушающий плагин получает игрока, купленный узел, старый и новый ранг, id и payload. Например, плагин квестов может по сигналу talent.mining.rank открыть нужный квест.

Если действие завершилось ошибкой

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

Каждый запуск получает постоянный ID и состояние PENDING, SUCCEEDED или FAILED. Автоматических повторов нет, но можно проверить запись и повторить её вручную. Для нескольких неудачных действий доступен массовый повтор только состояния FAILED: -dry-run показывает объём и доступность игроков, а -confirm заново пересчитывает набор, показывает стартовую сводку и запускает повтор. После выполнения выводится количество успешных и оставшихся FAILED. Игрок должен быть в сети; недоступные действия остаются FAILED.

Сброс таланта не отменяет уже выполненные одноразовые действия.