Перейти к содержанию

Справочник общих функций

В данном разделе собраны глобальные функции, которые доступны в любом скрипте QOFA.

Справка по вызову

Функции вызываются стандартным образом: название_функции(параметр1, параметр2, ...).

  • Если перед именем параметра стоит знак вопроса (например, ?userId), этот параметр является необязательным, и его значение по умолчанию равно nil.
  • Если указано значение (например, count = 1), это значение будет использовано по умолчанию, если параметр опущен.

Системные и строковые функции

  • echo(text) / println(text) — вывод текста в поток (как есть или с переносом строки). Подходит для отладки.
  • strtolower(text) — перевод строки в нижний регистр.
  • strtoupper(text) — перевод строки в верхний регистр.
  • ireplace(str, search, replace) — замена подстроки search на replace в строке str без учёта регистра. !!! info "Подсказка" Эти методы добавлены для удобства, однако для полноценной работы со строками вы также можете использовать стандартную библиотеку string языка Lua.

Работа с переменными (Хранилище данных)

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

  • set(param, value, ?userId = nil) — сохранить переменную param со значением value для текущего игрока (или для игрока с указанным userId).
  • get(param, default = nil, ?userId = nil) — получить значение переменной param. Если переменная не найдена, вернёт значение default.
  • setg(param, value) — сохранить глобальную переменную param со значением value, действующую на весь квест для всех пользователей.
  • getg(param, default = nil) — получить значение глобальной переменной param.
  • multi_set(params, value) / mset(params, value) — установить одно значение сразу для нескольких переменных. Пример: mset({'var1', 'var2', 'var33'}, 0)

Управление состоянием игры и очистка

  • CLEAR_GAME_DATA() — полное удаление всех переменных (как глобальных, так и пользовательских) текущего квеста. Используется для полного сброса.
  • CLEAR_USER_DATA(?userId) — удалить все переменные текущего или указанного игрока. Глобальные переменные затронуты не будут. Подходит для кнопки «Сбросить прогресс».
  • user_kick(?userId) — исключить игрока из квеста со сбросом всего прогресса (инвентарь, переменные, задания). Игрок сможет зайти в квест заново и начать сначала.

Вспомогательные функции и массивы

  • format_seconds(from_seconds) — форматирование секунд в строку формата Часы:Минуты:Секунды (и дни, если применимо).

  • array_foreach(array, 'callback') — применение функции обратного вызова к элементам массива.

    Внимание

    Имя функции callback нужно передавать строкой, а не саму функцию как замыкание.

  • array_rand(array, defaultValue = nil) — возвращает случайный элемент из массива или defaultValue.

  • array_push(array, value) — добавляет элемент в массив и возвращает изменённый массив.

Задания 📝

  • add_task(task_id, user_id) — выдаёт указанное задание пользователю без принудительного перехода на него (полезно для фоновых процессов или таймеров).
  • close_task(task_id?, user_id?) — закрыть (убрать) задание для пользователя. Время прохождения этого задания не запишется в статистику.
  • is_tasks_done(taskIds, user_id?) — возвращает true, если все задания из переданного массива ID выполнены.
  • is_task_done(task_id, user_id?) — возвращает true, если задание с указанным ID завершено (успешно или провалено).
  • task_set_done(task_id?, user_id?) — отметить задание как успешно выполненное.
  • task_set_failed(task_id?, user_id?) — отметить задание как проваленное.
  • get_task_answers(task_id) — получить список всех введённых ответов пользователя на это задание.
  • get_task_last_answer(task_id) — получить последний введённый ответ на задание.
  • search_tasks(name) — поиск заданий по фрагменту строки в заголовке (поиск ведётся как с начала, так и с конца строки).

Инвентарь 📦

Предметы можно получать по их внутреннему id или по уникальному названию (задаётся в редакторе). Рекомендуется использовать названия для переносимости скриптов между форками квестов (так как ID при импорте/экспорте могут измениться).

  • add_inventory(idOrName, count = 1, user_id = nil) — добавить предмет игроку.
  • inventory_count(idOrName, user_id = nil) / inv_count(...) — получить количество предметов у игрока.
  • has_inventory(idOrName, user_id = nil) — проверить наличие предмета у игрока.
  • pop_inventory(idOrName, count = 1, user_id = nil) — удалить указанное количество предметов (в отрицательное значение счётчик не уходит).
  • inventory_drop(idOrName, user_id = nil) — полностью удалить предмет у игрока, независимо от количества.
  • inventory_get(idOrName) — получить объект описания предмета инвентаря по имени или ID.
  • inventory_search(name) — поиск предметов по началу их названия.
  • inventory_all() — получить вообще все доступные в квесте объекты инвентаря.

Игровые очки и валюта

Для работы очков необходимо предварительно настроить валюту в основных настройках квеста (задать склонения числительных).

  • score_add(value, user_id = nil) — добавить очки игроку.
  • score_get(user_id = nil) — получить текущие очки игрока.
  • score_set(value, user_id = nil) — установить точное количество очков.
  • score_subtract(value, allow_less_zero = false, user_id = nil) — вычесть очки. Если allow_less_zero = false, баланс не упадёт ниже нуля.

Уведомления и интеграции

Всплывающие уведомления (Flash)

Данные сообщения сохраняются в сессии и отображаются пользователю при следующем обновлении интерфейса.

  • Flash:addInfo(text, caption = 'Информация')
  • Flash:addSuccess(text, caption = 'Успех!')
  • Flash:addWarning(text, caption = 'Предупреждение')
  • Flash:addError(text, caption = 'Ошибка')

Оповещения в Telegram 📱

  • user_can_notify(?userId = nil) — проверить, привязан ли Telegram у пользователя и можно ли отправить ему уведомление.
  • user_notify(message, ?userId = nil) — отправить текстовое уведомление игроку в Telegram. Поддерживается разметка Markdown2! Возвращает true в случае успеха.

Внешние HTTP-запросы (API)

Позволяют взаимодействовать с внешними умными устройствами или сторонними серверами. Принимать внешние запросы можно через раздел “Веб-хуки и АПИ”.

  • http_get(url) — выполнить GET-запрос. При ошибке возвращает false, а описание ошибки записывается в глобальную переменную LAST_ERROR.
  • http_post(url, post_params) — выполнить POST-запрос, где post_params — ассоциативный массив с полями.
  • http_header_add(name, value) — добавить или обновить HTTP-заголовок для последующих запросов. Пример: http_header_add("Content-Type", "application/json")
  • http_headers_get() — возвращает текущие установленные заголовки.
  • http_headers_clear() — очистить список кастомных заголовков.