Протокол используется как для web-приложения, так и для отдельных клиентов. Запрос к серверу — обычный POST-запрос в кодировке UTF-8. Ответ сервера — объект, сериализованный в JSON.

Для идентификации пользователя используется идентификатор сессии. Отдельные клиенты получают сессию при авторизации. В случае с web-клиентом код сессии может внедряться в код клиента — в этом случае он не должен совпадать с кодом обычной сессии, хранящейся в куках, что служит защитой от CSRF-атак.

Версия протокола, разумеется, не последняя, в будущем наверняка появятся новые. Чтобы упростить жизнь игрокам и разработчикам клиентов, сервер, реализующий протокола версии N, обязан поддерживать работу с клиентами, реализущими версию N-1. Также желательно поддерживать и более ранние версии.

Новый сервер совместим с клиентом, использующим старую версию протокола, если:

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

Две версии протокола совместимы, если в новой версии имеются только следующие отличия от старой:

• добавлены новые типы запросов, использование которых не требуется;
• в существующие типы запросов добавлены необязательные поля (или элементы полей), использование которых не требуется;
• для полей в существующих типах запросов добавлены новые типы или возможные значения, использование которых не требуется;
• добавлены новые типы ответов, которые могут быть выданы только на новые типы запросов;
• в существующие типы ответов добавлены новые поля, которые клиент может игнорировать;
• добавлены новые коды ошибок (ответ «nack»).

Для совместимости клиенты должны выполнять следующие требования:

• клиент должен игнорировать все неизвестные ему поля ответов;
• клиент не должен полагаться на код ошибки (поле «ErrorCode») или ее текст (поле «Error»).

В случае с массивами и объектами генерируется отдельное поле запроса для каждого скалярного элемента или поля всех уровней вложенности. Имя такого поля имеет форму имя_объекта[ключ_или_индекс1][ключ_или_индекс2]… Например, год[2012][декабрь][21].

Для задания времени используется число, представляющее метку времени UNIX.

Массив, отсортированный по убыванию времени окончания боя. Формат элемента:

Массив, содержащий от 1 до 9 карт программы. Карта представлена в виде объекта:

Голова змеи всегда смотрит вверх. Описание строк карты является объектом:

Линия карты длиной n клеток задается строкой из 2×n символов. Первый символ пары задает набор элементов:

Соответствующие символы в нижнем регистре обозначают инвертированные наборы элементов; так, например, символ «t» означает «все, кроме хвоста своей змеи». Второй символ пары задает группу, к которой принадлежит шаблон:

Строка описывает часть линии карты слева направо с координаты (X; Y). Если длина строки слишком велика, то остаток строки переносится на следующую линию с координаты (0; Y + 1). Например, объект {X: 6, Y: 2, Line: «A1B2C3»} описывает клетки с координатами (6; 2), (0; 3), (1; 3). «Переполнение» последней линии карты является ошибкой.

Массив. Формат элемента:

Массив. Формат элемента:

Массив. Формат элемента:

Массив, осортирован по названию окраски. Формат элемента:

Массив из 10 элементов, null для отсутствующих. Формат элемента:

Массив. Формат элемента:

Массив из 4 элементов, содержащих описания змей, null для отсутствующих. Элемент является объектом:

Массив из 4 элементов, содержащих информацию о змеях, участвовавших в бою, null для отсутствующих. Элемент является объектом:

DebugData является строкой, кодирующей последовательность решений змеи на каждом ходу. Каждый символ кодирует число в диапазоне 1 – 79, равное ASCII-коду символа минус 32 («!» – «o»). Число состоит из двух или трех полей:

Если используется карта:

Если карта не используется:

В случае, если отладочная информация для змеи недоступна (чужая обычная змея или в бою участвуют меньше 4 змей), то соответствующий элемент массива содержит null.

Массив из 4 строк длиной от 1 до 6 различных символов. Каждая строка задает пользовательский набор элементов. Элементы кодируются следующими символами:

Другие символы недопустимы. Порядок символов не имеет значения.

Массив из 1 – 1000 чисел, кодирующих очередность и направления шагов. Формат:

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

Направление движения змеи:

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

Все поля, перечисленные в описании запроса, обязательны (если в описании явно не указано иное). Помимо перечисленных полей запрос должен содержать поле Sid (если в описании запроса не указано иное). Также запрос может содержать необязательное поле RequestId. В этом случае ответ сервера будет содержать одноименное поле, содержимое которого совпадает с этим полем запроса.

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

• relogin, если время жизни сессии истекло либо данные авторизации были изменены;
• nack, если в запросе есть ошибки;
• error, если произошла внутренняя ошибка сервера.

При авторизации используется хэш-функция SHA1, ее реализацию для JavaScript можно найти, например, здесь. На входе функции — строка в кодировке UTF-8, на выходе — шестнадцатиричное текстовое представление хэша в нижнем регистре (40 символов 0 – 9, a – f). Примеры:

SHA1(SHA1(«hello»)) == «9cf5caf6c36f5cccde8c73fad8894c958f4983da»
SHA1(SHA1(«привет»)) == «60a72cfc2aa27af4b1bda6d18cf50a27046914c4»

получение информации о сервере

Request: «info»
Sid: не требуется (игнорируется)

ответ: «info»

получение информации о текущем пользователе

Request: «whoami»

ответ: «whoami»

получение данных (соль, штамп сервера) для авторизации

Request: «login data»
Sid: не требуется (игнорируется)
Login:

ответ: «login data»

авторизация и открытие сессии

Request: «login»
Sid: не требуется (игнорируется)
Login:
Timestamp:
Hash:

ответ: «login»

выход и закрытие сессии

Request: «logout»

ответ: «ack»

таблица рейтингов игроков

Request: «ratings»
FirstIndex: необязательно, по умолчанию 0
Count: необязательно, 1 – 50, по умолчанию 30
SortBy: необязательно, возможные ключи: PlayerName или Rating, по умолчанию [«>Rating»]

ответ: «ratings»

список игроков, отсортированный по имени

Request: «player list»
FirstIndex: необязательно, по умолчанию 0
Count: необязательно, 1 – 50, по умолчанию 30
SortBy: необязательно, возможные ключи: PlayerName, по умолчанию [«<PlayerName»]

ответ: «player list»

информация об игроке

Request: «player info»
PlayerId:

ответ: «player info»

список всех змей

Request: «snake list»
SnakeTypes: необязательно, по умолчанию «BN»
FirstIndex: необязательно, по умолчанию 0
Count: необязательно, 1 – 50, по умолчанию 30
SortBy: необязательно, возможные ключи: SnakeName или PlayerName, по умолчанию [«<SnakeName», «<PlayerName»]

ответ: «snake list»

получение списка вариантов окраски змей

Request: «skin list»

ответ: «skin list»

информация о змее

Request: «snake info»
SnakeId:

ответ: «snake info»

создание новой змеи

Request: «snake new»
SnakeName:
SnakeType:
SkinId:
ProgramDescription:
Templates:
Maps:

ответ: «snake new»

удаление своей змеи

Request: «snake delete»
SnakeId:

ответ: «ack»

редактирование змеи

Request: «snake edit»
SnakeId:
SnakeName: необязательно
SnakeType: необязательно
SkinId: необязательно
ProgramDescription: необязательно
Templates: необязательно
Maps: необязательно

ответ: «ack»

назначение своей обычной змеи бойцом

Request: «snake assign»
SnakeId:

ответ: «ack»

список боев игрока

Request: «fight list»
FightListType:

ответ: «fight list»

информация о бое

Request: «fight info»
FightId:

ответ: «fight info», «fight delayed»

начать бой со временной змеей; временная змея будет первой

Request: «fight test»
TurnLimit: необязательно
SnakeName:
SkinId:
ProgramDescription:
Templates:
Maps:
OtherSnakeIds:

ответ: «fight info», «fight delayed»

начать обычный бой

Request: «fight train»
TurnLimit: необязательно
SnakeIds:

ответ: «fight info», «fight delayed»

начать рейтинговый бой

Request: «fight challenge»
PlayerIds:

ответ: «fight info», «fight delayed»

отменить бой

Request: «fight cancel»

ответ: «ack»

список сохраненных боев

Request: «slot list»

ответ: «slot list»

загрузить информацию о сохраненном бое

Request: «slot view»
SlotIndex:

ответ: «slot view»

сохранить информацию о бое

Request: «slot save»
SlotIndex:
SlotName:
FightId:

ответ: «ack»

изменение описания сохраненного боя

Request: «slot rename»
SlotIndex:
SlotName:

ответ: «ack»

очистить сохраненный бой

Request: «slot delete»
SlotIndex:

ответ: «ack»

обновление сессии

Request: «ping»

ответ: «ack»

Все поля, перечисленные в описании ответа, обязательны (если в описании явно не указано иное). Если в запросе было поле RequestId, то ответ также содержит это поле с тем же значением. В будущих версиях протокола могут появиться дополнительные поля ответов; старые версии клиентов должны игнорировать такие поля.

Сообщение об ошибке может быть выдано в ответ на любой запрос.

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

Response: «relogin»

ошибка в запросе

Response: «nack»
ErrorCode:
Error:

внутренняя ошибка

Response: «error»
ErrorCode:
Error:

подтверждение выполнения запроса

Response: «ack»

информация о сервере

Response: «info»
Version:
Compatible:
Lifetime:

информация о текущем игроке

Response: «whoami»
PlayerId:
PlayerName:
FightId: текущий отложенный бой (null, если отложенных боев нет)
Rating: отсутствует, если игрок не участвует в рейтинге
SnakeId: ид бойца; отсутствует, если игрок не участвует в рейтинге
SnakeName: имя бойца; отсутствует, если игрок не участвует в рейтинге
SkinId: окраска бойца; отсутствует, если игрок не участвует в рейтинге

данные для авторизации; если в запросе «login data» указан неизвестный логин, это не считается ошибкой

Response: «login data»
Login:
Salt:
Timestamp:

успешная авторизация

Response: «login»
PlayerId:
PlayerName:
Sid:

таблица рейтингов

Response: «ratings»
FirstIndex:
SortBy:
TotalCount:
Ratings:

список игроков

Response: «player list»
FirstIndex:
SortBy:
TotalCount:
PlayerList:

информация об игроке

Response: «player info»
PlayerId:
PlayerName:
Rating:
SnakeId: идентификатор бойца или null
PlayerSnakes:

список змей

Response: «snake list»
SnakeTypes:
FirstIndex:
SortBy:
TotalCount:
SnakeList:

список вариантов окраски

Response: «skin list»
SkinList:

информация о змее

Response: «snake info»
SnakeId:
SnakeName:
SnakeType:
SkinId:
PlayerId:
PlayerName:
ProgramDescription: необязательно, выдается только для ботов и своих змей
Templates: необязательно, выдается только для ботов и своих змей
Maps: необязательно, выдается только для ботов и своих змей

создана новая змея

Response: «snake new»
SnakeId:

список боев

Response: «fight list»
FightListType:
FightList:

информация о бое

Response: «fight info»
FightId:
FightType:
FightTime:
FightResult:
TurnLimit:
Turns:
Snakes:
SnakeStats:

расчет боя не завершен

Response: «fight delayed»
FightId:

список сохраненных боев

Response: «slot list»
SlotList:

информация о сохраненном бое

Response: «slot view»
SlotIndex:
SlotName:
FightType:
FightTime:
FightResult:
TurnLimit:
Turns:
Snakes:
SnakeStats:

В будущих версиях протокола могут появиться новые (более специфические) коды ошибок.