Функции движка

Оглавление

Встроенные функции движка позволяют скриптам взаимодействовать с игровым процессом: управлять уровнями и инфоблоками, получать статистику, изменять переменные других команд и выводить сообщения.

Все функции вызываются глобально. Большинство функций принимает в качестве аргумента объект с параметрами.

Запрос новых функций

API движка постоянно развивается под нужды авторов. Если для реализации вашей идеи не хватает встроенных функций, вы можете запросить их добавление. Это бесплатно, при условии, что предложенный функционал универсален и может быть полезен в других квестах, а не привязан жестко к специфичной логике одной конкретной игры.

Управление действиями и интерфейсом

`AddAction`

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

Параметры: Объект со следующими базовыми свойствами:
- action (Строка) — тип выполняемого действия.
- teams (Число | Массив) — ID команды или массив ID команд, для которых применяется действие.
- args (Объект) — параметры конкретного действия. Состав объекта args строго зависит от переданного action:

Варианты параметра action и соответствующие им args:

'Finish' — завершить игру для указанных команд.
- Объект args не требуется (игнорируется).
'LevelOpen' — открыть уровень (или несколько уровней).
- args.ids (Число | Массив) (Обязательно) — ID уровня или массив ID уровней для открытия.
'LevelClose' — закрыть уровень (или несколько уровней).
- args.ids (Число | Массив) (Обязательно) — ID уровня или массив ID уровней для закрытия.
'InfoblockOpen' — открыть инфоблок.
- args.ids (Число | Массив) (Обязательно) — ID инфоблока или массив ID.
- args.levels (Число | Массив) (Опционально) — ID уровня или массив ID уровней. Если указано, действие применится только к инфоблокам на этих уровнях.
'InfoblockClose' — закрыть инфоблок.
- args.ids (Число | Массив) (Обязательно) — ID инфоблока или массив ID.
- args.levels (Число | Массив) (Опционально) — ID уровня или массив ID уровней.
- args.force (Boolean | Число) (Опционально) — принудительное закрытие блока.
'InfoblockSetVisibility' — изменить настройки видимости инфоблока.
- args.ids (Число | Массив) (Обязательно) — ID инфоблока или массив ID.
- args.levels (Число | Массив) (Опционально) — ID уровня или массив ID уровней.
- (Обязательно наличие хотя бы одного из следующих трех параметров). Доступные значения статусов: 'VISIBLE', 'HIDDEN', 'CONTENT':
  - args.beforeOpen (Строка) — статус видимости до открытия.
  - args.whenOpen (Строка) — статус видимости в открытом состоянии.
  - args.afterClose (Строка) — статус видимости после закрытия.
'RunTimer' — запустить таймер.
- args.alias (Строка) (Обязательно) — алиас таймера для запуска.
- args.duration (Число) (Обязательно) — количество секунд таймера.
Возвращает: undefined

Примеры использования

javascript

// Пример 1: Открытие уровня
AddAction({
  action: 'LevelOpen',
  teams: teamId,
  args: { ids: 42 }
});

// Пример 2: Изменение видимости инфоблока на конкретном уровне
AddAction({
  action: 'InfoblockSetVisibility',
  teams: teamId,
  args: { 
    ids: [10, 11], 
    levels: 5,
    afterClose: 'HIDDEN' // Скрыть блок после закрытия
  }
});

// Пример 3: Финиш игры для всех соперников
AddAction({
  action: 'Finish',
  teams: rivals
});

`CancelAction`

Прерывает цепочку выполнения текущего перехода.

Параметры: нет
Возвращает: undefined

Пример

javascript

if (ctx.team.money < 100) {
  CancelAction();
}

WARNING

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

`FlashMessage`

Отправляет всплывающее сообщение в игровой клиент.

Параметры: Объект со свойствами:
- level (Строка) — тип сообщения: 'SUCCESS', 'ERROR', 'WARNING', 'NEUTRAL'.
- message (Строка) — текст сообщения.
Возвращает: undefined

Пример

javascript

FlashMessage({ level: 'SUCCESS', message: 'Код принят!' });

`Log`

DANGER

Только для разработчиков Quest Quiz.

Записывает сообщение или объект в системный лог выполнения скрипта.

Параметры: (Любой тип) — строка, число или объект для логирования.
Возвращает: undefined

Работа с переменными команд

Эти функции позволяют читать и изменять переменные любых команд, а не только той, для которой выполняется скрипт.

`GetTeamVar`

Возвращает значение переменной указанной команды.

Параметры: Объект со свойствами:
- teamId (Число) — ID команды.
- name (Строка) — имя переменной.
Возвращает: (Любой тип) — значение переменной (или 0, если не задана).

`ModifyTeamVar`

Увеличивает или уменьшает числовое значение переменной для указанных команд.

Параметры: Объект со свойствами:
- teams (Число | Массив) — ID команды или массив ID.
- name (Строка) — имя переменной.
- change (Число) — значение, на которое нужно изменить текущее (может быть отрицательным).
Возвращает: undefined

Пример

javascript

// Списываем 50 монет у всех соперников
ModifyTeamVar({ teams: rivals, name: 'money', change: -50 });

`SetTeamVar`

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

Параметры: Объект со свойствами:
- teams (Число | Массив) (Обязательно) — ID команды или массив ID команд.
- name (Строка) (Обязательно) — имя переменной.
- value (Любой тип) (Обязательно) — новое значение, которое будет присвоено переменной.
Возвращает: undefined

Пример

javascript

// Устанавливаем флаг блокировки для команд-соперников
SetTeamVar({
  teams: rivals,
  name: 'isBlocked',
  value: 1
});

// Сбрасываем счетчик подсказок для всех команд
SetTeamVar({
  teams: teams,
  name: 'hintsUsed',
  value: 0
});

Коды

`GetCodeData`

Возвращает полную информацию о коде по различным критериям поиска на текущем уровне.

Параметры: Объект со свойствами (используется одно из):
- id (Число) — поиск по ID кода.
- alias (Строка) — поиск по текстовому алиасу кода.
- code (Строка) — поиск по точному совпадению введенного текста с одним из значений кода.
- regex (Строка) — поиск по регулярному выражению (проверяется совпадение с вариантами кода).
Возвращает: (Объект | null) — объект с данными кода или null, если код не найден.

Структура возвращаемого объекта:

id (Число) — уникальный идентификатор кода.
level (Число) — ID уровня, к которому привязан код.
name (Строка) — название кода (как задано в редакторе).
code (Массив строк) — массив допустимых значений кода (варианты ввода).
scanned_always_pass (Boolean) — флаг: всегда ли код принимается при сканировании (например, QR-кода).
change_time (Строка | null) — строковое представление интервала изменения времени (штраф или бонус), привязанного к коду.
is_regex (Boolean) — флаг: являются ли значения в массиве code регулярными выражениями.
team_id (Число | null) — ID команды, если код является индивидуальным для конкретной команды.
code_name (Строка | null) — текстовый алиас кода.
sort (Число | null) — индекс сортировки кода.

Пример

javascript

const codeInfo = GetCodeData({ regex: code });

if (codeInfo && codeInfo.team_id && codeInfo.team_id !== teamId ) {
  FlashMessage({ level: 'ERROR', message: 'Это код другой команды' });
  CancelAction();
}

`GetCodeAlias / GetCodeIdByAlias`

Конвертация между ID кода и его текстовым алиасом.

Параметры: ID кода (для GetCodeAlias) или алиас (для GetCodeIdByAlias).
Возвращает: (Строка | Число) — алиас или ID соответственно.

`GetCodeIdsByAliasRegex`

Возвращает массив ID кодов, чьи алиасы совпадают с регулярным выражением.

Параметры: (Строка) — регулярное выражение.
Возвращает: (Массив) — список ID кодов.

`CodePassedCount`

Возвращает количество прохождений указанных кодов (сколько раз коды были вбиты).

Параметры: (Число | Массив) — ID кода или массив ID.
Возвращает: (Число) — количество прохождений.

`CodePassedByRegexCount / CodePassedByAliasRegexCount`

Возвращает количество прохождений кодов, найденных по регулярному выражению (по значению кода или по его алиасу).

Параметры: Объект со свойствами:
- regex (Строка) — регулярное выражение.
- teams (Массив) — массив ID команд.
- levels (Массив) — массив ID уровней.
- unique (Boolean) — (только для AliasRegex) считать ли только уникальные коды.
Возвращает: (Число) — количество прохождений.

Инфоблоки

`GetBlockAlias / GetBlockIdByAlias`

Конвертация между ID инфоблока и его текстовым алиасом.

Параметры: ID блока (для GetBlockAlias) или алиас (для GetBlockIdByAlias).
Возвращает: (Строка | Число) — алиас или ID соответственно.

`GetBlockIdsByAliasRegex`

Возвращает массив ID инфоблоков, чьи алиасы совпадают с регулярным выражением.

Параметры: (Строка) — регулярное выражение.
Возвращает: (Массив) — список ID блоков.

`GetOpenBlocks`

Возвращает массив ID открытых инфоблоков.

Параметры: Объект с опциональными фильтрами: levels, blocks, teams.
Возвращает: (Массив) — список ID блоков.

`GetTeamIdsWithOpenBlock`

Возвращает массив ID команд, у которых открыт указанный инфоблок.

Параметры: Объект со свойствами blocks (ID блока/блоков) и опционально levels.
Возвращает: (Массив) — список ID команд.

`GameBlocksByAliasRegexCount / OpenBlocksByAliasRegexCount / ClosedBlocksByAliasRegexCount`

Группа функций для подсчета инфоблоков по регулярному выражению алиаса. Считают общее количество в игре, количество открытых или количество закрытых (пройденных) блоков соответственно.

Параметры: Объект со свойствами:
- regex (Строка) — регулярное выражение.
- teams (Массив) — массив ID команд (для открытых/закрытых).
- levels (Массив) — массив ID уровней.
- unique (Boolean) — считать ли только уникальные инфоблоки.
Возвращает: (Число) — количество блоков.

`GetAcceptedTermsNames`

Возвращает массив названий выполненных (принятых) критериев для инфоблоков команды.

Параметры: (Число | Объект {team_id}) — ID команды.
Возвращает: (Массив) — список названий критериев.

Уровни и игра

`GetTeams`

Возвращает список всех команд, участвующих в текущей игре. Автоматически учитывает режим игры (для тестовой игры возвращаются тестовые команды, для реальной — реальные).

Параметры: Нет
Возвращает: (Массив объектов | null) — массив с данными команд.

Структура объекта команды в массиве:

id (Число) — уникальный идентификатор команды.
name (Строка) — название команды.
avatar (Строка | null) — URL аватара команды.

Пример

javascript

const allTeams = GetTeams();

if (allTeams && allTeams.length > 0) {
  // Вычисляем урон от выстрела в зависимости от количества команд
  ctx.game.shotDamage = ctx.game.config.maxHp / ctx.game.config.maxShots / allTeams.length;
  
  // Отправляем информационное сообщение текущей команде
  FlashMessage({ 
    level: 'NEUTRAL', 
    message: `Каждый выстрел наносит ${ctx.game.shotDamage} единиц урона.`,
  });
}

`GetLineup`

Возвращает список игроков (состав) указанной команды в текущей игре. Если параметры не переданы, автоматически возвращает состав текущей команды.

Параметры: Нет, либо ID команды (Число), либо объект { teamId: Число }.
Возвращает: (Массив объектов | пустой массив) — массив с данными игроков.

Структура объекта игрока в массиве:

id (Число) — уникальный идентификатор пользователя.
nickname (Строка) — никнейм пользователя.

Пример

javascript

// Получаем состав текущей команды (без передачи параметров)
const myTeamLineup = GetLineup();

if (myTeamLineup && myTeamLineup.length > 0) {
  // Формируем строку с никнеймами через запятую
  const playerNames = myTeamLineup.map(p => p.nickname).join(', ');
  
  FlashMessage({
    level: 'INFO',
    message: `В вашей команде ${myTeamLineup.length} игроков: ${playerNames}`
  });
}

// Получаем состав другой команды, передав её ID
const enemyTeamId = 123;
const enemyLineup = GetLineup(enemyTeamId);
// Альтернативный вызов: GetLineup({ teamId: 123 });

if (enemyLineup.length === 0) {
  // Логика, если в команде противника нет игроков
}

`GetLevelAlias / GetLevelIdByAlias`

Конвертация между ID уровня и его текстовым алиасом.

Параметры: ID уровня (для GetLevelAlias) или алиас (для GetLevelIdByAlias).
Возвращает: (Строка | Число) — алиас или ID соответственно.

`GameTeamsCount`

Возвращает общее количество команд, участвующих в игре.

Параметры: нет
Возвращает: (Число) — количество команд.

Бонусы и штрафы

`ChangeTime`

Добавляет или вычитает секунды из бонуса/штрафа для кода, уровня или инфоблока.

Параметры: Объект со свойствами:
- type (Строка) — тип сущности: code, level', block.
- id (Число | Массив) — ID сущности.
- teams (Число | Массив) — ID команды или массив ID.
- seconds (Число) — количество секунд (может быть отрицательным).
Возвращает: undefined

`SetChangeTime`

Устанавливает точное значение бонуса/штрафа для кода, уровня или инфоблока.

Параметры: Объект со свойствами:
- type (Строка) — тип сущности: code, level, block.
- id (Число | Массив) — ID сущности.
- teams (Число | Массив) — ID команды или массив ID.
- value (Строка) — строковое представление интервала (например, '00:05:00' или '123 sec').
Возвращает: undefined

Сетка (Грид)

`SetGridCellImage`

Устанавливает изображение в определенную ячейку сетки инфоблока.

Параметры: Объект со свойствами:
- cell (Строка) — координаты ячейки в формате 'A1' или '1-1'.
- blockId (Число) — ID инфоблока.
- image (Строка) — URL изображения.
- teams (Число | Массив) — ID команды или массив ID.
Возвращает: undefined

`SetGridCellImageByCode`

Устанавливает изображение в ячейку сетки, привязанную к конкретному коду (через связи инфоблоков и сеток).

Параметры: Объект со свойствами:
- teamId (Число) — ID команды.
- codeId (Число) — ID кода.
- image (Строка) — URL изображения.
Возвращает: undefined

Функции движка ​

Управление действиями и интерфейсом ​

AddAction ​

CancelAction ​

FlashMessage ​

Log ​

Работа с переменными команд ​

GetTeamVar ​

ModifyTeamVar ​

SetTeamVar ​

Коды ​

GetCodeData ​

GetCodeAlias / GetCodeIdByAlias ​

GetCodeIdsByAliasRegex ​

CodePassedCount ​

CodePassedByRegexCount / CodePassedByAliasRegexCount ​

Инфоблоки ​

GetBlockAlias / GetBlockIdByAlias ​

GetBlockIdsByAliasRegex ​

GetOpenBlocks ​

GetTeamIdsWithOpenBlock ​

GameBlocksByAliasRegexCount / OpenBlocksByAliasRegexCount / ClosedBlocksByAliasRegexCount ​

GetAcceptedTermsNames ​

Уровни и игра ​

GetTeams ​

GetLineup ​

GetLevelAlias / GetLevelIdByAlias ​

GameTeamsCount ​

Бонусы и штрафы ​

ChangeTime ​

SetChangeTime ​

Сетка (Грид) ​

SetGridCellImage ​

SetGridCellImageByCode ​

Функции движка

Управление действиями и интерфейсом

`AddAction`

`CancelAction`

`FlashMessage`

`Log`

Работа с переменными команд

`GetTeamVar`

`ModifyTeamVar`

`SetTeamVar`

Коды

`GetCodeData`

`GetCodeAlias / GetCodeIdByAlias`

`GetCodeIdsByAliasRegex`

`CodePassedCount`

`CodePassedByRegexCount / CodePassedByAliasRegexCount`

Инфоблоки

`GetBlockAlias / GetBlockIdByAlias`

`GetBlockIdsByAliasRegex`

`GetOpenBlocks`

`GetTeamIdsWithOpenBlock`

`GameBlocksByAliasRegexCount / OpenBlocksByAliasRegexCount / ClosedBlocksByAliasRegexCount`

`GetAcceptedTermsNames`

Уровни и игра

`GetTeams`

`GetLineup`

`GetLevelAlias / GetLevelIdByAlias`

`GameTeamsCount`

Бонусы и штрафы

`ChangeTime`

`SetChangeTime`

Сетка (Грид)

`SetGridCellImage`

`SetGridCellImageByCode`