Операторы и основные функции: XML, MD и Lua

Как пользоваться памяткой#

Сначала определите язык. Одинаковое намерение записывается по-разному в XPath, MD и Lua. Таблицы ниже — выбранные конструкции, нужные для чтения примеров этой вики и исходников проекта. Это не статистический рейтинг всех файлов X4 и не полный справочник.

Если термины пока незнакомы, начните со статьи как работает код X4. Все новые фрагменты здесь учебные; запуск в игровом мире для них не заявлен.

Четыре базовых понятия#

Переменная хранит значение: например, число товаров. Условие отвечает, выполнять ли действие. Функция принимает аргументы и выполняет работу; иногда возвращает результат. Обработчик события — функция или узел MD, который вызывается при определённом событии.

Различайте объявление, вызов и результат. В Lua local function getName() ... end объявляет функцию, getName() вызывает её, а local name = getName() сохраняет ответ.

XML: элементы, атрибуты и селекторы#

Символ & внутри атрибута XML записывают как &, < — как <. Это правила XML, ещё до разбора выражения MD. Поэтому в условиях удобно читать lt, le, gt, ge. Селектор diff и значение do_if имеют разные грамматики.

MD: небольшое действие за действием#

Это имена элементов MD, а не стандартные функции XML. Их атрибуты и допустимый контекст определяет движок. Например, run_actions требует соответствующую library, а event_ui_triggered находится в условиях cue.

Учебный фрагмент для actions, где $Items создаётся здесь же:

<set_value name="$Items" exact="['Корпус', 'Двигатель']" />
<set_value name="$Count" exact="0" />
<do_for_each name="$Item" in="$Items">
  <set_value name="$Count" operation="add" exact="1" />
</do_for_each>
<do_if value="$Count == 2">
  <debug_text text="'Обработано два элемента'" />
</do_if>

После цикла $Count равен 2. operation="add" exact="1" означает прибавить единицу. Имя $Item обозначает текущий элемент; здесь его содержимое не используется.

Выражения MD#

MD-списки в показанных примерах начинаются с 1. $Value? не означает «значение истинно»: существующая переменная может содержать false. Существование переменной и существование объекта — разные проверки. Контекст переменных особенно важен в экземплярах cue; подробности — в отдельной статье.

Lua: чтение обычной функции#

local function total(items)
    if type(items) ~= "table" then
        return 0
    end
    local result = 0
    for _, item in ipairs(items) do
        result = result + item.amount
    end
    return result
end

local amount = total({{amount = 3}, {amount = 5}})

Это самостоятельный пример языка без функций X4. amount получается равным 8. У каждого элемента предполагается числовое поле amount.

{} создаёт таблицу. В Lua таблицы используются и как списки, и как записи с именованными полями. item.amount равно item["amount"]. В for _, item первая переменная получает индекс; _ — обычное имя, которым автор показывает «это значение мне не нужно».

Операторы Lua#

Не полагайтесь на #table как на число произвольных ключей: таблица с пропусками или строковыми ключами не является плотным списком. Длина строки считается в байтах, что важно для UTF-8.

В Lua ложными считаются false и nil; 0 и пустая строка истинны. Выражение value or fallback выбирает запасной вариант также при value == false. and/or возвращают выбранное значение, а не обязательно true или false. Точная основа языка — Lua 5.1; расширения LuaJIT сверяются с его документацией.

Стандартные функции Lua#

Не каждый стандартный модуль обязательно доступен в игровом окружении. Например, наличие debug или файловых операций нельзя выводить из одного знакомства с обычной Lua. pcall возвращает флаг и ответ/ошибку; проглоченная ошибка может скрыть проблему. Неверный нативный вызов не становится безопасным из-за pcall.

Функции X4 и собственные функции мода#

Последние два имени приведены только для различения происхождения API. Они не доступны в обычном одиночном моде без кода соответствующего проекта.

ID объекта нужно получить заранее в нужной форме. Не подставляйте в GetComponentData случайное число или имя корабля. Строковый сетевой ID, UI handle и 64-битный UniverseID нельзя свободно менять местами: подробнее о типах ID.

Пять ошибок, которые легко заметить при чтении#

1. В Lua неравенство пишется ~=, в MD — !=.
2. Соединение строк в Lua — .., в MD встречается +.
3. = в Lua присваивает значение; сравнение записывается ==.
4. Изменение текста собственного окна ещё не означает изменение объекта мира.
5. Объявить обработчик недостаточно: файл должен загрузиться, событие — прийти, вход — пройти проверки.

Для практики прочитайте обмен Lua ↔ MD и попробуйте своими словами объяснить каждую строку до установки примера в тестовый профиль.