This is an old revision of the document!
API для написания своей версии фронтенда
Можно использовать для телеграмм ботов, нативных приложений или браузерных расширений
Точки входа
Все действия производятся через две точки входа
game.php - Авторизация, получение заданий, отправка ответов, разблокировка штрафных подсказок.
game_au.php - Проверка есть ли новые действия от других игроков, которые надо отобразить. Например, кто-то вбил верный ответ.
Во все запросы надо добавлять GET параметр json. Тогда результат будет приходить в формате JSON.
Авторизация
Используется game.php
GET параметры:
gid надо задать ID игры.
POST параметры:
user - логин игрока
pass - пароль игрока
Надо сохранить cookie и их все передавать их в последующие запросы.
Если в ответе будет строка с именем login_error - значит авторизация не удалась
Данные задания
Используется game.php
GET параметры:
gid - ID игры.
tid - [Опционально] ID уровня
В ответ приходит JSON в utf-8 c кучей опциональных данных, если возле типа ? значит может отсутствовать.
Имена классов и типы не приходят - они просто для иллюстрации.
class PublicContext {
int version = 1; // Версия протокола
?string error; // Ошибка.
?string login_error; // Ошибка при логине
?int game_id; // ID игры
?int task_id; // ID текущего уровня
?int user_id; // ID залогиненого игрока
?string user_name; // login игрока
?int team_id; // ID команды игрока, в одиночных играх может совпадать с ID текущего игрока
?int refresh_time_ms; // Время последнего обновления страницы unix_time миллисекундах
?int refresh_check_limit_ms; // Промежуток времени в миллисекундах, в течении которого не надо без причины дергать сервер.
PublicGame game; // Данные об игре
/*?PublicGamep[]*/ available_games; // Данные об активных/ближайших играх домена. Доступно, если вызвать без gid
PublicTask task; // Данные о текущем задании
PublicLastAnswers last_answers; // Мониторинг недавно вбитых ответов
?PublicAnswerResult answer_result; // Результат последнего вбития ответов
?PublicAnswerForm answer_form; // Данные о форме ответов
/* ?[n => PublicCode] */ codes; // Данные о кодах
/* ?PublicHint[] */ hints; // Подсказки
?int n_bonuses; // Общее число бонусов, если они есть в задании
?int compact_n_bonuses; // Общее число бонусов, если автор выбрал компактный режим бонусов
?int compact_bonus; // Суммарный полученный бонус/штраф, если автор выбрал компактный режим бонусов
/* ?string[] */ compact_bonus_answers; // Известные ответы на бонусы, если автор выбрал компактный режим бонусов
/* ?string[] */ compact_bonus_hints; // Подсказки на вбитые бонусы, если автор выбрал компактный режим бонусов
/* ? PublicBonus[] */ bonuses; // Бонусы
/* ? PublicBonus[] */ global_bonuses; // Сквозные бонусы
/* ?PublicTaskButton[] */ active_tasks; // Доступные сейчас задания
/* ?PublicTaskButton[] */ closed_tasks; // Уже закрытые задания - только в штурме
}
class PublicGame {
string name; // Название игры
int start_time_ms; // Время старта игры в unix_time миллисекундах
int end_time_ms; // Время окончания игры в unix_time миллисекундах
?int type; // Тип игры - 0 или отсутсвует - штурмовая последовательность, 1 - линейная последовательность
?bool single; // Одиночная или командная игра
}
class PublicTask {
int n; // Номер задания
string name; // Название задания
string task; // Текст задания
string answer_format; // Формат ответа
int n_codes; // Сколько всего кодов в задании
int need_n_codes; // Сколько надо кодов для прохождения задания
?int start_time_ms; // Время начала задания в unix_time миллисекундах
?int time_left_ms; // Сколько осталось времени в миллисекундах до автоперехода
?int delay_left_ms; // Задержка в миллисекундах до появления задания
int is_complete; // Задание уже закончено
}
class PublicLastAnswers {
/* ?PublicLastAnswer[] */ answers; // Массив с информацией об ответах
int last_update_ms; // Время последнего обновления в unix_time миллисекундах
}
class PublicLastAnswer {
int time_ms; // Время в unix_time миллисекундах, когда ответ отправлен
?string user; // Кто вбил - в одиночных играх нет
string answers; // Вбитые ответы через запятую
string type; // Одно значени из right, wrong, repeat - правильно, но уже было, nonsubmit - не приняты из-за блокировки
?string bonus; // Полученный бонус или штраф за ответы
}
class PublicAnswerResult {
int task_id; // ID уровня для которого посчитано
/* ?strings[] */ right_answers = []; // правильные ответы
/* ?strings[] */ wrong_answers = []; // неправильные
/* ?strings[] */ repeat_answers = []; // правильные, но повторные
/* ?strings[] */ nonsubmit_answers = []; // не принятые из-за блокировки
?string bonus = ''; // Бонус полученные за ответы
?string penalty = ''; // Штраф полученный за ответы
}
class PublicAnswerForm {
public bool show_finish_task = false; // Надо ли показывать кнопку закрывающую задание. Если надо то задание можно закрыть отправив код !finish!
bool hide_answer_form = false; // Ответы больше приниматься не будут, можно убрать поле ввода
?int block_time_left_ms; // Сколько осталось до снятия ограничения на ввод. Время в миллисекундах. Если penalty не 0, значит ответы можно вводить, но со штрафом за неправильные.
?int limit_n_answers; // Ограничение на число неправильных ответов. Константа - как задана автором.
?int time_limit; // Время в секундах. За какой промежуток времени учитывается ограничение на число ответов limit_n_answers. Если 0, то limit_n_answers - ограничение на весь уровень.
?int penalty; // Штраф за каждый неправильный ответ сверх допустимого
?int n_answers_left; // Сколько ответов команда может вбить до того как будет ограничение. Меняется после каждого вбития ответов. Если 0 - значит ограничение активно.
}
class PublicCode {
?string name; // Название кода
?string answer; // Ответ на код
}
class PublicBonus {
int n; // Номер бонуса
int bonus; // Получаемый бонус или штраф, если значение отрицательное. В секундах или баллах
?string answer; // Ответ на бонус
?string description; // Описание бонуса (загадка)
?string hint; // Подсказка, если бонус решен
?int time_to_open_ms; // Время в миллисекундах до открытия бонуса
?int time_to_close_ms;// Время в миллисекундах секундах до закрытия бонуса
?bool is_closed; // Время на ввод бонуса истекло - больше для ввода ответов он недоступен
}
class PublicHint {
int n; // Номер Подсказки
?int time_to_open_ms; // Время в миллисекундах до открытия подсказки
?int id; // ID штрафной подсказки - надо для ее использования
?string description; // Описание подсказки
?string hint; // Текст подсказки
?int penalty; // Штраф за штрафную подсказку
?int any_code; // Если есть значит подсказка может открыть любой код
/*int[]*/ codes; // Список кодов, которые может открыть подсказка
}
Варианты ошибок
в error могут прийти такие ошибки:
- NO_GAME_ID - не указан gid
- NO_GAME - неправильный gid
- NO_USER - надо залогиниться
- NO_TEAM - командная игра, а игрок не в команде
- TEAM_NO_ANONYMOUS - анонимный игрок не может играть в игры с ограничением состава
- TEAM_TOO_BIG - в команде больше игроков, чем ограничение состава
- TEAM_GAME_NOT_REQUESTED - команда не подала заявку
- TEAM_GAME_NOT_ACCECPTED - команда не принята в игру
- GAME_NOT_STARTED - игра еще не началась
- GAME_FINISHED - игра закончена
- SEQUENCE_ERROR - ошибка в назначенной автором последовательности уровней.
Отправка ответов
Используется game.php
GET параметры:
gid - ID игры.
tid - ID уровня в который надо вбить ответ. Если не задавать, то есть риск вбить ответ с прошлого уровня в уровень с ограничением на ввод.
a - Ответы, которые надо вбить, через запятую.
Взятие штрафных подсказок
Используется game.php
GET параметры:
gid - ID игры.
hint_id - ID подсказки, которую надо разблокировать.
hint_code - [Опционально] номер кода, который надо открыть штрафной подсказкой.
Обновление страницы
Используется game_au.php, game.php
Если игра командная, то в ответе на game.php будет приходить refresh_check_limit_ms
Это время в миллисекундах, через которое можно проверять есть ли изменения в движке от действий сокомандников.
Если дергать сервер чаще, то есть риск получить бан по IP на какое-то время.
refresh_check_limit_ms - не константа и может меняться в зависимости от нагрузки на сервер.
Если любой из таймеров в игре заканчивается раньше, чем refresh_check_limit_ms то надо обновить страницу с помощью game.php. При этом refresh_check_limit_ms - можно проигнорировать.
Оптимально
С помощью game_au.php проверяем, надо ли обновлять страницу.
GET параметры:
gid - ID игры.
tid - ID задания.
time - время полученное в refresh_time из ответа game.php.
В ответ придет JSON:
class PublicAutoUpdateResult {
?string $error; // Ошибка
?bool $refresh; // Надо обновить страницу, кто-то вбил правильный код или взял штрафную подсказку
?bool $reload; // Кто-то прошел уровень
?bool $refersh_monitoring; // Есть новые неправильные ответы в мониторинге. Можно их загрузить, если надо.
?int $next_check_ms; // Сколько ждать(в миллисекундах) до следующей проверки - вычисляется сервером в зависимости от нагрузки
}
Если в JSON есть поля refresh, reload или refersh_monitoring, то с помощью game.php обновляем страницу.
Не оптимально
С помощью game.php регулярно загружаем новую версию.
В этом случае период с которым дергаете сервер берите как refresh_check_limit_ms умноженный на 3.