Сделать мутатор

Что такое мутатор

Мутатор — это небольшой пакет .oamut поверх основной игры или любого мода. Он меняет один матч. Библиотека устанавливает его в папку Mutators под id из манифеста, и установка его не включает. Игрок включает его сам для схватки, лобби или кампании. works-with указывает, к каким модам он подходит, а звёздочка означает любой мод и основную игру.

Пакет

В корне папки лежит oamut.yaml. Рядом с ним — входной скрипт: mutator.lua, если entry не называет другой, и никогда не в files/, rules/ или lua/. В lua/ лежит остальной исходный код Lua, и только эти файлы читает require. В files/ лежат байты, которые может добавить слой Files. В rules/ лежат файлы правил с именами на .sm. Значок — это PNG, который называет манифест. Заметка с именем на .md или .txt предназначена для людей, и игра её не загружает. Файл вне этого списка отклоняется. При сравнении регистр букв ASCII не учитывается.

Манифест

Строгий YAML по тем же правилам, что и профиль мода: один документ, одно отображение верхнего уровня, без якорей и блочных скаляров. Файл начинается с oamut, равного целому числу 1. Ключ, которого нет в стандарте, отклоняется. Значение, которое начинается со знака «больше», и звёздочку берите в кавычки, иначе парсер примет их за что-то другое. Поэтому requires.engine пишется в кавычках. Версия тоже пишется в кавычках: простое число отклоняется.

Восемь тегов

Парсер принимает любой тег в kebab-case строчными буквами длиной от 1 до 32 байт, не больше четырёх. Для этих восьми id при точном совпадении Библиотека рисует значок и переведённую подпись. Любой другой id показывается так, как написан, без значка. Если манифест не называет icon, значок пакета берётся у первого тега, когда этот id — один из восьми.

План

Входной скрипт определяет mutate. Движок вызывает mutate(ctx) один раз, в фазе плана, и сам этот вызов игру не меняет. mutate возвращает одну таблицу. Пустая таблица ничего не меняет. Ключ, которого движок не знает, отклоняется.

files — это таблица из add и mask. Каждый из них — список строк, и любой можно опустить. add называет папки в пакете по порядку, и если путь есть в обеих, побеждает более поздняя папка. mask скрывает пути. rules — это список готовых блоков, созданных через where, all, named или on и затем :change, а также путей sm, которые указывают на файл .sm. Изменение — это set, scale, lock, remove или append. scale может принимать нижнюю и верхнюю границы, и граница ограничивает только этот один множитель. Хуки — это функции. Они выполняются в таком порядке: units, weapons, features, sides, tables, затем menus. maps выполняется после всех мутаторов и только когда в матче выбрана карта. hacks задаёт на этот один матч параметр, который реестр открывает для мутаторов. Запись в слой разрешает именно его объявление.

Параметры и ctx

Во время mutate в ctx есть мод (его id, версия и игра), версия движка, параметры и ctx.incompatible. Если мод не включён, ctx.mod.id равен ta-3.1c. Вызов ctx.incompatible с причиной останавливает этот мутатор, и причина — это текст, который увидит игрок. Коллекции ещё не загружены. Хук может читать units, weapons, features, sides, tables и menus из ctx без объявления слоя. Для записи слой нужен.

В ctx.options по одному полю на каждый id параметра. Переключатель — true или false. Число, а также выбор, значения которого — числа, дают число. Выбор, значения которого — идентификаторы, даёт текст. Параметр, который игрок не трогал, имеет значение по умолчанию. type — toggle, choice или number. Выбор перечисляет от 2 до 16 значений, только числа или только идентификаторы, а также labels, когда слова отличаются от значений. У числа есть min, max, step и default. Игрок может выбрать только значение от min до max, которое попадает на шаг, поэтому скрипту не нужно снова проверять диапазон: значение вне шага отклоняется до запуска скрипта. id параметра — это имя Lua, и ключевое слово Lua отклоняется.

Песочница

Скрипт выполняется как Lua в одной песочнице. У него нет файлов, сети, часов, окружения и процессов. io, os, debug, package и coroutine не открыты, а предкомпилированный чанк отклоняется. Каждый чанк — исходный код. Два мутатора не делят никакого состояния.

Каждая фаза начинается заново с полного лимита инструкций, 50 000 000, и с полного лимита реального времени, 10 секунд. Предел памяти — 64 МиБ, и для следующей фазы он заново не выдаётся. Одна строка — не больше 65 536 байт. Для характеристики, которую вычисляет скрипт, используйте fixed. Он считает в 65 536-х долях, поэтому один и тот же скрипт пишет один и тот же текст на любой машине. pairs обходит ключи в фиксированном порядке. Результат не зависит от машины.

Стек

Игрок выстраивает мутаторы по порядку, и они применяются сверху вниз. Первый применяется первым. Каждый следующий видит игру такой, какой её оставили те, что выше. Мутаторы, названные в requires.mutators, включаются вместе с этим и применяются раньше него, в том порядке, в котором их записывает этот список. Больше 32 мутаторов, id, указанный дважды, требование, которое не выполняет ни один мутатор выше, или два конфликтующих мутатора — и отклоняется весь список, ничего не запускается.

Сначала накладываются файлы всех мутаторов в порядке списка, и за путь побеждает более поздний мутатор. Затем каждый мутатор в том же порядке читает свои файлы юнитов, оружия и download как записи, применяет свои правила и запускает свои хуки. Правила применяются по одному изменению за раз в фиксированном порядке. Множитель умножает текущее число, а ограничение действует только на этот множитель, а не на последующие. Присваивание заменяет текущее значение. lock задаёт значение и не даёт ни одному последующему мутатору менять это поле. Внутри одного блока Lua изменения выполняются по имени поля после приведения ASCII к нижнему регистру, а не в том порядке, в котором написана таблица. Усреднения между мутаторами нет. Когда применились все мутаторы, число юнита или оружия, выходящее за разрядность, в которой его хранит игра, и число объекта за пределами диапазона, который читает игра, один раз прижимается к краю этого диапазона.