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

Lua-скриптинг: Программы поведения

webapp_banner.jpg

Программа поведения заменяет нативный ИИ моба поведениями на Lua, которые решают, куда он движется, куда смотрит, какую сущность выбирает целью и когда атакует. EliteMobs запускает эти программы в нативной системе Brain Minecraft через среду выполнения Mind из MagmaCore.

Программы поведения — это не Lua-способности. Lua-способность реагирует на события босса, например on_boss_damaged_by_player; программа поведения выполняется каждый тик и управляет движением моба. Босс может использовать и то и другое: поведение может попросить способности босса выполнить действие через on_mind_action.

Поведения питомцев FreeMinecraftModels — это файлы ai.module в том же формате, которые подчиняются тем же правилам. Особенности, относящиеся к питомцам, включая поля контекста c.pet и c.settings, описаны в разделе Модули поведения питомцев. Поведения мобов FreeMinecraftModels, которые берут на себя моба, созданного не плагином, — это снова файлы того же вида, с c.overlay и c.settings.

Доступность в сборках

Поведения мобов FreeMinecraftModels требуют релиз FreeMinecraftModels после 2.15.0.

Выбор программы

Задайте behavior в файле пользовательского босса, как описано в разделе Создание боссов, или в файле свойств моба для типа сущности. behavior: native сохраняет ванильный ИИ. Если версия сервера не поддерживает нативный Mind, EliteMobs при запуске выводит в журнал Native Mind interface is unavailable on this Minecraft version.. Тогда пользовательский босс, выбравший программу, не спавнится, а в журнал записывается Cannot spawn <boss file>: .... Босс, чей behavior указывает на отсутствующую или некорректную программу, точно так же не спавнится на любой версии.


Файлы​

Файлы поведения находятся в plugins/EliteMobs/behaviors/. EliteMobs записывает следующие встроенные файлы, если их нет:

plugins/
EliteMobs/
behaviors/
basic_melee.lua
modules/
target.lua
pursuit.lua
melee.lua
wander.lua
  • Файл .lua внутри любой папки с именем modules является модулем. Любой другой файл .lua является программой.
  • Босс ссылается на программу по её пути относительно behaviors/, например basic_melee.lua или guards/patrol_guard.lua.
  • EliteMobs загружает файлы поведения при запуске своей службы Mind. Файл, не прошедший проверку, пропускается, а в консоль выводится Could not load behavior <file> или Could not load behavior module <file> с указанием причины.
  • ID программ и модулей используют пространство имён elitemobs, например elitemobs:behavior/basic_melee. ID пишутся строчными буквами и могут содержать a-z, 0-9, ., _ и -, а после двоеточия ещё и /. Две программы не могут иметь одинаковый ID, и каждый ID модуля должен объявляться только в одном файле.
  • Одно пространство имён вмещает не более 256 модулей. Модуль может перечислить не более 32 зависимостей, программа может подключить не более 64 модулей, а каждый исходный файл ограничен 1 000 000 символов.

Песочница и загрузка​

Действуют те же правила песочницы, что и для других Lua-скриптов. См. раздел Песочница Lua. Файлы поведения отличаются в двух отношениях:

  • coroutine недоступен.
  • xpcall никогда не вызывает свой обработчик сообщений. Он возвращает false и простое сообщение об ошибке, поэтому используйте pcall.

Каждый файл компилируется при загрузке, а не для каждого моба, и его код верхнего уровня выполняется тогда же для проверки. Каждый моб, выполняющий программу, получает собственную среду Lua и заново выполняет код верхнего уровня программы и её модулей, поэтому локальные переменные файла не разделяются между мобами. Глобальная переменная, заданная файлом, видна только этому файлу. Каждый запуск должен возвращать одни и те же id, revision и modules или dependencies.

Код верхнего уровня программы и всех её модулей делит один лимит из 250 000 инструкций Lua и 50 миллисекунд процессорного времени. Если в момент запуска программы уже выполняется другой вызов Lua, например скрипт, который спавнит моба, код верхнего уровня использует оставшийся лимит этого вызова. Оставляйте в коде верхнего уровня только определения и константы.


Файл программы​

Файл программы возвращает ai.program { ... }:

return ai.program {
id = 'elitemobs:behavior/basic_melee', revision = 1,
modules = {
'elitemobs:behavior/target', 'elitemobs:behavior/pursuit',
'elitemobs:behavior/melee', 'elitemobs:behavior/wander'
},
budget = {
callback_micros = 2000, entity_micros = 4000, server_micros = 5000,
max_callbacks = 20, max_instructions = 12000, max_action_requests = 2
}
}
ПолеТипПримечания
idстрокаОбязательно. ID с пространством имён, elitemobs:... для файлов в behaviors/. Он не может совпадать с ID одного из модулей программы.
revisionположительное целоеОбязательно.
modulesмассив строкНеобязательно. ID модулей, чьи памяти, сенсоры и поведения входят в программу. Зависимости загружаются раньше модулей, которым они нужны. Дубликаты и циклические зависимости отклоняются.
memories, sensors, behaviorsтаблицыНеобязательно. Программа может объявлять собственные элементы в том же формате, что и модуль.
budgetтаблицаНеобязательно. Мягкие ограничения планирования. См. Бюджеты.
runawayтаблицаНеобязательно. Жёсткие ограничения на каждый колбэк. См. Бюджеты.

Файл модуля​

Файл модуля возвращает ai.module { ... } и объединяет многократно используемые памяти, сенсоры и поведения:

ПолеТипПримечания
idстрокаОбязательно. ID модуля с пространством имён.
revisionположительное целоеОбязательно.
dependenciesмассив строкНеобязательно. ID других модулей, которые нужны этому модулю.
memoriesтаблицаНеобязательно. См. Памяти.
sensorsмассивНеобязательно. Записи ai.sensor { ... }.
behaviorsмассивНеобязательно. Записи ai.behavior { ... }.
settingsтаблицаНеобязательно. Именованные значения по умолчанию, которые плагин-хост может переопределять для каждого существа. См. Настройки модуля.

sensors, behaviors, modules и dependencies должны быть простыми массивами без пропусков и именованных ключей. Имена сенсоров, поведений и памятей должны быть уникальны во всех модулях программы.

Настройки модуля​

settings объявляет настраиваемые значения модуля и их значения по умолчанию:

settings = {
radius = 8,
glow = true,
mode = 'circle',
foods = { 'minecraft:apple', 'minecraft:carrot' }
}
ЗначениеПример
конечное числоradius = 8
true или falseglow = true
текстmode = 'circle'
список текстовfoods = { 'minecraft:apple' }

Каждый ключ должен быть именем. Список должен быть простым массивом текстов без пропусков и именованных ключей. Любое другое значение, например функция или таблица именованных значений, приводит к отклонению модуля. Таблица читается как написана; метатаблица у неё игнорируется.

MagmaCore только проверяет значения по умолчанию и передаёт их плагину-хосту, который решает, как их видят скрипты. EliteMobs не читает настройки модулей, поэтому в файлах behaviors/ они ни на что не влияют. Питомцы FreeMinecraftModels накладывают значения каждого существа поверх значений по умолчанию и передают колбэкам модуля его собственные настройки как c.settings. См. Модули поведения питомцев. Поведения мобов FreeMinecraftModels, которым нужен релиз FreeMinecraftModels после 2.15.0, делают то же самое со значениями, которые задаёт переопределение; см. Поведения мобов.


Памяти​

Памяти — это типизированные значения, которые сенсоры и поведения используют совместно для одного моба. Объявите каждую по имени:

memories = {
candidate = { type = 'uuid', persistent = false },
next_attack = 'integer'
}
ТипЗначение Lua
stringстрока
booleanлогическое значение
integerцелое число
numberчисло
uuidстрока UUID
position{ world = 'world', x = 0, y = 64, z = 0 }

Имя без двоеточия помещается в пространство имён программы. persistent по умолчанию равно false; true помечает память для сериализации вместе с сохранённым состоянием Mind. Читайте и записывайте памяти через c.memory:get(name), c.memory:set(name, value, ttl_ticks), c.memory:forget(name) и c.memory:contains(name). Третий аргумент set необязателен; если он указан, значение истекает через это количество тиков. Использование необъявленного имени вызывает ошибку.


Сенсоры​

Сенсор собирает информацию, обычно в памяти. Сенсоры выполняются раньше поведений.

ai.sensor {
id = 'elitemobs:behavior/find_target', interval = 20,
sense = function(c)
local target = c.perception:nearest_player(35)
if target then c.memory:set('candidate', target.uuid, 21)
else c.memory:forget('candidate') end
end
}
ПолеТипПо умолчаниюПримечания
idстрокаОбязательно.
intervalположительное целое1Тики между запусками.
senseфункцияОбязательно. Получает контекст Mind.

Сенсоры не могут использовать c.actuator; вызов метода актуатора из сенсора вызывает ошибку.

Тайминг сенсоров​

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


Поведения​

Поведение воздействует на моба, пока удерживает объявленные им элементы управления.

ai.behavior {
id = 'elitemobs:behavior/attack', priority = 10,
controls = { ai.controls.attack },
can_start = function(c) return c.perception:current_target() ~= nil end,
can_continue = function(c) return c.perception:current_target() ~= nil end,
tick = function(c)
local target = c.perception:current_target()
if target then c.actuator:attack(target) end
end
}
ПолеТипПо умолчаниюПримечания
idстрокаОбязательно.
priorityцелое число0Меньшие числа имеют приоритет.
controlsмассивнетЭлементы управления, которые это поведение арендует, пока выполняется.
probe_intervalцелое число1Тики между проверками can_start, пока поведение остановлено. Не менее 1; значения выше 200 считаются равными 200. См. Интервал проверки.
can_startфункциявсегда trueДолжна возвращать true или false.
can_continueфункциякак can_startДолжна возвращать true или false.
startфункциянетВыполняется один раз при запуске поведения.
tick_intervalцелое число1Тики между запусками can_continue и tick, пока поведение работает. Не менее 1; значения выше 200 считаются равными 200. Нужна версия EliteMobs после 10.9.14 или версия FreeMinecraftModels после 2.15.0.
tickфункцияОбязательно. Выполняется каждый тик, пока поведение работает, или каждые tick_interval тиков.
stopфункциянетfunction(c, reason); выполняется при остановке поведения.

Жизненный цикл​

  1. Пока поведение остановлено, оно проверяет can_start каждый тик или каждые probe_interval тиков. Когда функция возвращает true и поведение может арендовать все объявленные элементы управления, выполняется start.
  2. Каждый тик, пока поведение работает, или каждые tick_interval тиков, и всегда на тике запуска, сначала выполняется can_continue. Если она возвращает false, поведение останавливается с причиной completed; иначе выполняется tick.
  3. stop(c, reason) получает одну из причин: completed, preempted, program_replaced, entity_removed, callback_failed или handle_closed. Остановка освобождает элементы управления поведения и прекращает удерживаемые им движение, выбор цели или атаку.

Ошибка Lua в can_continue, start или tick останавливает поведение с причиной callback_failed. Возврат из can_start или can_continue чего-либо, кроме логического значения, считается ошибкой. Для каждого сбоя в консоль выводится Mind <program> callback <callback> failed with ....

Интервал проверки​

По умолчанию остановленное поведение проверяет can_start на каждом тике. При probe_interval = N оно проверяет каждые N тиков, на собственной фазе для каждого моба, поэтому толпа мобов с одним и тем же поведением или несколько поведений одного моба не проверяют условие на одном и том же тике. Используйте это, когда условие запуска затратное или ответ не нужен на точном тике.

  • Первая проверка после того, как тело начинает обрабатываться, ждёт фазы поведения, не более N - 1 тиков.
  • Поведение запускается и забирает элементы управления у другого поведения не более чем на N - 1 тиков позже, чем могло бы.
  • Поведение, которое останавливается, проверяется снова на своём следующем тике фазы, не более чем через N тиков.
  • Проверка, пропущенная из-за того, что моб достиг бюджета, или запуск, отложенный им, повторяется на следующем тике, а затем возвращается на фазу.
  • Пока поведение работает, ничего не меняется: can_continue и tick по-прежнему выполняются каждый тик или каждые tick_interval тиков, а stop не откладывается. Поведение без can_continue всё равно вызывает can_start каждый тик, пока работает, потому что can_continue по умолчанию равен can_start.

Значение должно быть числом без дробной части, 1 или больше; всё остальное приводит к отклонению файла. Значения выше 200 (10 секунд) считаются равными 200.

Элементы управления​

Элемент управленияРазрешает
ai.controls.movec.actuator:move_to(...), c.actuator:flee(...), c.actuator:stop_moving()
ai.controls.lookc.actuator:look_at(...)
ai.controls.move и ai.controls.look вместеc.actuator:steer_flight(...)
ai.controls.jumpc.actuator:jump()
ai.controls.targetc.actuator:set_target(...), c.actuator:clear_target()
ai.controls.attackc.actuator:attack(...), c.actuator:shoot(...)
ai.controls.actionc.actions:request(...)
ai.controls.use_itemЗарезервировано; у Lua-актуатора нет метода для предметов.

Каждый элемент управления принадлежит одновременно только одному работающему поведению. Поведение с меньшим числом priority забирает элемент управления у поведения с большим числом, и то останавливается с причиной preempted. Забрать элемент управления у поведения с меньшим числом нельзя. При равных приоритетах элемент управления получает поведение, чей id идёт первым по алфавиту. Вызов метода актуатора без удержания соответствующего элемента управления вызывает ошибку. c.actuator:stop_all() останавливает только то, что удерживает поведение.

Во встроенных модулях выбор цели использует приоритет 5, атаки ближнего боя — 10, преследование — 20, а праздное блуждание — 50, поэтому преследование забирает движение у блуждания, как только появляется цель.

Бегство, стрельба и задание урона​

Доступность в сборках

Эти три вызова требуют версии EliteMobs после 10.9.14.

  • c.actuator:flee(location, speed) прокладывает путь примерно в десять блоков, ведущий прочь от точки, и следует по нему. Возвращает false, когда тело не может прокладывать пути, не находит такого длинного выхода или его движением управляет другая система. Планирование пробует несколько путей выхода, поэтому вызывайте его раз в несколько тиков; в промежутках путь продолжает выполняться.
  • c.actuator:shoot(target) выполняет дальнюю атаку, свойственную типу тела: стрела скелета, зелье ведьмы или арбалет разбойника, который сначала заряжается, если пуст. Возвращает false для типа, у которого такой атаки нет.
  • c.actuator:attack(target, damage) делает взмах и наносит столько урона, засчитанного телу, вместо собственного урона от атаки тела.

Управление полётом​

c.actuator:steer_flight(x, y, z) перемещает летающее тело с этой скоростью, в блоках за тик, только на текущий тик. Вызывайте его на каждом тике, пока моб должен продолжать лететь; на тике без вызова тело снова движется по обычной навигации. Вызов прерывает любой путь, начатый через move_to, сталкивается с блоками и поворачивает тело в сторону горизонтального движения не более чем на 8 градусов за тик. Скорость больше 4 блоков за тик (80 блоков в секунду) уменьшается до 4 в том же направлении.

Поведение должно удерживать оба элемента управления, ai.controls.move и ai.controls.look. Отсутствие элемента управления или значение, не являющееся конечным числом, вызывает ошибку. Вызов возвращает false и ничего не делает, если тело не умеет летать или его движением управляет другая система, а в остальных случаях возвращает true. EliteMobs даёт летающее тело мобам летающих типов, таким как летучие мыши, ифриты, гасты, фантомы и вредины.

Запрос действий босса​

Поведение, удерживающее ai.controls.action, может вызвать c.actions:request(identifier, payload). EliteMobs передаёт запрос Lua-способностям босса через on_mind_action. Идентификатор должен быть ключом с пространством имён в нижнем регистре длиной не более 128 символов, например 'elitemobs:slam'. Полезная нагрузка содержит не более 16 записей с ключами в нижнем регистре длиной не более 64 символов, а строковые значения ограничены 256 символами; недопустимый идентификатор или полезная нагрузка вызывают ошибку. Вызов возвращает accepted, deferred или rejected; запросы сверх max_action_requests программы за один тик возвращают deferred. Формат полезной нагрузки описан в разделе Контекст действия Mind.


Бюджеты​

budget задаёт мягкие ограничения планирования. Когда моб достигает одного из них за тик, среда выполнения Mind пропускает оставшиеся колбэки этого моба до следующего тика. Уже выполняющийся колбэк всегда завершается. Пропущенный запуск сенсора или проверка can_start повторяется на следующем тике.

КлючПо умолчаниюПримечания
callback_micros2000Колбэк, выполняющийся дольше, завершает колбэки моба на этот тик.
entity_micros4000Общее время колбэков на одного моба за тик.
server_micros20000Колбэки моба прекращаются на этот тик, как только все программы Mind вместе израсходовали столько времени.
max_callbacks128Колбэков на одного моба за тик.
max_action_requests8Запросов действий на одного моба за тик; не более 64.

Все значения должны быть положительными, callback_micros не может превышать entity_micros, а тот не может превышать server_micros.

runaway задаёт жёсткие ограничения, прерывающие отдельный колбэк:

КлючПо умолчаниюМаксимумПримечания
cpu_micros5000050000Процессорное время потока на один колбэк.
max_instructions50000250000Инструкций Lua на один колбэк.

budget также принимает max_instructions, как во встроенном basic_melee.lua. Объявляйте его в budget или в runaway, но не в обоих. Оба ограничения должны быть положительными. Большее значение всё равно загружается, но без предупреждения снижается до максимума.

Ограничения останавливают колбэк прямо во время выполнения, поэтому бесконечный цикл приводит к сбою, а не к зависанию сервера. Инструкции считаются по мере выполнения; процессорное время проверяется каждые 1 024 инструкции и при возврате из колбэка. Если сервер не может измерить процессорное время потока, cpu_micros ограничивает прошедшее время значением, в пять раз большим. Колбэк, превысивший жёсткое ограничение, завершается сбоем так же, как при любой другой ошибке колбэка, а в строке консоли будет failed with RUNAWAY_LIMIT_EXCEEDED.


Следующие шаги​