поделиться с друзьями

API

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

Обсудить API можно на форуме.

Содержание

  1. Введение
  2. Методы
    1. Базовая информация
    2. Авторизация в игре
    3. Состояние авторизации
    4. Вход в игру
    5. Выход из игры
    6. Информация об игроке
    7. Информация об игре/герое
    8. Дневник героя
    9. Использование способности
    10. Выбор в задании
    11. Карты: взять
    12. Карты: объединить
    13. Карты: использовать
    14. Города: перечень всех городов
    15. Города: подробная информация о городе
    16. Мастера: подробная информация о Мастере
  3. Типы
    1. Артефакты: редкость
    2. Артефакты: типы
    3. Артефакты: типы экипировки
    4. Артефакты: эффекты
    5. Карты: типы
    6. Карты: редкость
    7. Герои: тип действия
    8. Города: специализация
    9. Города: аттрибуты
    10. Задания: типы актёров
    11. Здания: типы
    12. Игрок: тип способности
    13. Общее: пол
    14. Общее: раса
    15. Общее: черты
    16. Общее: честь
    17. Общее: миролюбие
    18. Прочее: состояние авторизации
    19. Прочее: состояние игры
    20. Мастер: профессия
    21. Мастер: тип социальной связи
    22. Мастер: косметические особенности характера
    23. Мастер: практические особенности характера
  4. Общие ошибки

Введение

Принципы взаимодействия

  • Взаимодействие происходит по протоколу http;
  • Ответ возвращается в формате JSON;
  • Сессии реализуются через передачу cookie с именем sessionid; в случае, если в запросе cookie не указана, сервер создаст новую сессию и вернёт соответствующее значение cookie;
  • Для защиты от CSRF (так как фунционал браузерной версии также построен на API), каждый POST запрос должен иметь cookie с именем csrftoken И либо POST параметр csrfmiddlewaretoken, либо заголовок X-CSRFToken, установленные в значение этой cookie. Значение для csrftoken cookie можно установить случайное (либо значение cookie будет установлено при 1-ом запросе к API).

    Значение csrftoken должно быть строкой из 64 символов (0-9,a-z).

  • Примеры запросов на логин с использованием curl:
    curl -b "sessionid=kwc2ngq02dilu56ti76nj21z18wzaghe csrftoken=wxiefxk7i6kvkUeyi4jU2xO0B96RwvJc" -d "email=email@gmail.com&password=11111"  -H "X-CSRFToken: wxiefxk7i6kvkUeyi4jU2xO0B96RwvJc" "http://localhost:8000/accounts/auth/api/login?api_version=1.0&api_client=SASS-asas"
    
    curl -b "sessionid=kwc2ngq02dilu56ti76nj21z18wzaghe csrftoken=wxiefxk7i6kvkUeyi4jU2xO0B96RwvJc" -d "email=email@gmail.com&password=111111&csrfmiddlewaretoken=wxiefxk7i6kvUeyi4jU2xO0B96RwvJc" "http://localhost:8000/accounts/auth/api/login?api_version=1.0&api_client=SASS-asas"
    

Формат запроса

Адрес каждого метода имеет следующий формат:

the-tale.org/<resource_path>/api/<method_name>?api_version=<method_version>&api_client=<client_id>&<method_arguments>

где:

  • resource_path — путь к игровой сущности (аккаунту, игре, рейтингам и т.п.);
  • method_name — название метода, может отсутствовать;
  • method_version — версия метода (в стандартном формате через точку: 1.0, 1.1 и т.п.);
  • client_id — идентификатор клиентского приложения;
  • method_arguments — аргументы, необходимые методу.

Версионность

  • Каждый метод может иметь одну или несколько версий;
  • Старшая версия считается основной, остальные — устаревшими;
  • При обращении к устаревшей версии метода, в ответе будет присутствовать соответствующий флаг-индикатор;
  • В рамках одной версии метода гарантируется сохранение формата вызова;
  • В рамках одной версии метода гарантируется недеструктивное сохранение поведения (сторонние эффекты, коды возвращаемых ошибок);
  • В рамках одной версии метода возможно недеструктивное изменение формата возвращаемых данных (могут быть добавлены новые поля, без изменения структуры существовавших ранее);
  • Устаревшие версии методов будут удаляться из игры по прошествии времени, достаточного для перехода активных проектов на новые версии методов.

Идентификатор клиента

  • Передача идентификатора клиента необходима для сбора разработчиками статистики и возможности проведения разного рода «магических» действий в случае его неадекватного поведения;
  • Формат идентификатора: <идентификатор программы>-<версия программы>, в идентификаторе должен быть ровно 1 дефис;
  • Значение идентификатора выбирается пользователями API, регистрировать идентификатор нигде не требуется;
  • На наш взгляд, лучшим решением будет составление идентификатора из аббревиатуры названия клиента и версии (или даты) его сборки.

Неблокирующие операции

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

Принцип работы неблокирующей операции:

  1. запрос клиента вызывает выполнение фоновой задачи на сервере;
  2. сервер возвращает ответ с информацией, по которой можно проверять статус выполнения задачи (со статусом "processing");
  3. клиент периодически проверяет статус выполнения (желательно, не чаще раза в секунду), пока не получит сообщение о её завершении (или об ошибке);
  4. после этого операция считается выполненой

Разница между «входом в игру» и «авторизацией в игре»

Для получения и изменения информации конкретного пользователя в API предусмотрено два метода: «вход в игру» и «авторизация в игре».

  1. «Вход в игру» требует от пользователя ввода логина и пароля. Это позволяет получать доступ к любым данным и производить любые действия от имени пользователя;
  2. «Авторизация в игре» не требует ввода логина и пароля. Она производится через выдачу пользователем разрешения на сайте игры. Приложение, получившее разрешение, не будет иметь доступ к наиболее важным данным и операциям пользователя (профилю, магазину и так далее).

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

Формат ответа

Ответ на любой корректный запрос в случае корректной работы сервера возвращается с кодом 200.

{
  "depricated": true,                  // поле устанавливается, при обращении к устаревшей версии метода

  "status": "ok"|"error"|"processing", // ok — запрос обработан корректно
                                       // error — произошла ошибка
                                       // processing — запрошена неблокирующая операция, идёт обработка запроса
  "code": "error.code",                // строка — уникальный код ошибки (присутствует только в случае ошибки)
  "error": "сообщение",                // сообщение об ошибке для пользователя (присутствует только в случае ошибки)

  // если ошибка в данных, вводимых пользователем, вместо "error" в ответ вставляется "errors" с перечислением
  // идентификатор поля — имя параметра, в котором передавался ввод пользователя
  "errors": {"идентификатор поля": ["сообщение 1", "сообщение 2"]},

  "status_url": "url"                  // адрес проверки статуса неблокирующей операции (формат статуса такой же)

  "data": {},                          // запрошенные данные, в случае корректного выполнения запроса
                                       // дополнительная информация об ошибке, в случае некорректного выполнения запроса
}

Методы

Базовая информация

Получение базовой информации о текущих параметрах игры и некоторых других данных.

  • адрес: /api/info/
  • http-метод: GET
  • версии: 1.0
  • параметры: нет
  • возможные ошибки: нет

формат данных в ответе:

{
  "static_content": "абсолютный url",    // базовый абсолютный путь к статическим игровым данным (например, картинкам)
  "game_version": "текущая.версия.игры", // текущая версия игры
  "turn_delta": <целое>,                 // задержка между ходами в секундах
  "account_id": <целое>|null             // идентификатор аккаунта, если пользователь вошёл в игру, иначе null
  "account_name": <строка>|null          // имя пользователя, если он вошёл в игру, иначе null
  "abilities_cost": {                    // цена использования способностей игрока
    <идентификатор способности>: <целое число>
  }
}

Абсолютные адреса возвращаются без указания протокола: //path/to/entity

Авторизация в игре

Авторизация приложения для проведения операций от имени пользователя. Приложению не будут доступны «критические» операции и данные (связанные с профилем пользователя, магазином и так далее).

  • адрес: /accounts/third-party/tokens/api/request-authorisation
  • http-метод: POST
  • версии: 1.0
  • параметры:
    • POST: application_name — короткое название приложения (например, его название в google play).
    • POST: application_info — краткое описание информации об устройстве пользователя (чтобы пользователь мог понять откуда пришёл запрос).
    • POST: application_description — описание приложения (без html разметки)
  • возможные ошибки: нет

формат данных в ответе:

{
  "authorisation_page": <url>, // адрес, на который необходимо направить пользователя для подтверждения авторизации
}

Алгоритм авторизации:

  • приложение делает запрос к этому методу;
  • в ответе приходит ссылка, по которой надо направить пользователя, и устанавливается значение cookie с именем sessionid, которое и является идентификатором сессии пользователя;
  • пользователь переходит по ссылке, на странице у него спрашивают разрешение на доступ к своим данным для данного приложения;
  • приложение (по таймеру или по нажатию кнопки пользователем) делает запрос к методу получения состояния авторизации;
  • ответ метода будет содержать информацию о статусе авторизации и о пользователе;
  • после успешной авторизации с API можно работать точно так же, как и после обычного входа в игру.

При успешном выполнении запроса, будет установлено значение cookie с именем sessionid, которая и является идентификатором сессии пользователя.

Запрос авторизации не хранится вечно, гарантируется его доступность в течение 10 минут после создания.

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

При «выходе из игры» разрешение, выданное приложению, удаляется.

Рекомендации:

  • Функцию выхода из игры рекомендуется реализовывать. Также рекомендуется выходить из игры при любой нобходимости релогина.
  • Не указывайте версию своей программы ни в одном из параметров запроса, т.к. они сохраняются на сервере и не будут изменяться при изменении версии.
  • Делайте подробное описание. Расскажите подробно о функционале программы.

Состояние авторизации

Метод возвращает состояние авторизации для текущей сессии. Обычно вызывается после запроса авторизации.

  • адрес: /accounts/third-party/tokens/api/authorisation-state
  • http-метод: GET
  • версии: 1.0
  • параметры: нет
  • возможные ошибки: нет

формат данных в ответе:

{
  "next_url": "относительный url",  // адрес, переданный при вызове метода или "/"
  "account_id": <целое число>,      // идентификатор аккаунта
  "account_name": <строка>,         // имя игрока
  "session_expire_at": <timestamp>, // время окончания сессии пользователя
  "state": <целое число>            // состояние авторизации, см. в списке типов
}

Вход в игру

Вход в игру. Используйте этот метод только если разрабатываете приложение для себя и друзей. В остальных случаях пользуйтесь «авторизацией в игре».

  • адрес: /accounts/auth/api/login
  • http-метод: POST
  • версии: 1.0
  • параметры:
    • GET: next_url — вернётся в ответе метода в случае успешного входа, по умолчанию равен "/"
    • POST: email — email адрес пользователя
    • POST: password — пароль пользователя
    • POST: remember — если флаг указан, сессия игрока будет сохранена на длительное время
  • возможные ошибки:
    • accounts.auth.login.wrong_credentials — неверный логин или пароль
    • accounts.auth.login.form_errors — ошибка(-и) в заполнении полей

формат данных в ответе:

{
  "next_url": "относительный url", // адрес, переданный при вызове метода или "/"
  "account_id": <целое число>,     // идентификатор аккаунта
  "account_name": <строка>,        // имя игрока
  "session_expire_at": <timestamp> // время окончания сессии пользователя
}

При успешном выполнении запроса, будет установлено значение cookie с именем sessionid, которая и является идентификатором сессии пользователя.

В случае, если от имени не вошедшего в игру пользователя будет произведён запрос функционала, доступного только авторизованным пользователям, API вернёт ошибку с кодом "common.login_required" (см. секцию с описанием общих ошибок).

Выход из игры

Выйти из игры

  • адрес: /accounts/auth/api/logout
  • http-метод: POST
  • версии: 1.0
  • параметры: нет
  • возможные ошибки: нет

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

Получить информацию об игроке

  • адрес: /accounts/<account>/api/show
  • http-метод: GET
  • версии: 1.0
  • параметры:
  • URL account — идентификатор игрока
  • возможные ошибки:
  • account.wrong_value — аккаунт с таким идентификатором не найден

формат данных в ответе:

{
  "id": <целое число>,           // идентификатор игрока
  "registered": true|false,      // маркер завершения регистрации
  "name": "строка",              // имя игрока
  "hero_id": <целое число>,      // идентификатор героя
  "places_history": [            // список истории помощи городам
    "place": {                   // город
      "id": <целое число>,       // идентификатор города
      "name": "строка"           // название города
    },
    "count": <целое число>       // количество фактов помощи
  ],
  "might": <дробное число>,      // могущество
  "achievements": <целое число>, // очки достижений
  "collections": <целое число>,  // количество предметов в коллекции
  "referrals": <целое число>,    // количество последователей (рефералов)
  "ratings": {                                // рейтинги
    "строка": {                               // идентификатор рейтинга:
      "name": "строка",                       // название рейтинга: иинформация о рейтинге
      "place": <целое число>,                 // место
      "value": <целое число>|<дробное число>  // величина рейтингового значения
    }
  },
  "permissions": {                // права на выполнение различных операций
    "can_affect_game": true|false // оказывает ли влияние на игру
  },
  "description": "строка"         // описание игока, введённое им сами (в формате html)
}

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

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

  • адрес: /game/api/info
  • http-метод: GET
  • версии: 1.6
  • параметры:
    • GET: account — идентификатор аккаунта
    • GET: client_turns — номера ходов, по отношению к которым можно вернуть сокращённую информацию о герое (только изменённые с этого времени поля).
  • возможные ошибки: нет

Если параметр account не будет указан, то вернётся информация об игре текущего пользователя, а на запрос от неавторизованного пользователя — общая информация об игре (без информации об аккаунте и герое).

Часть информации в ответе является личной и доступна только залогиненному игроку, для остальных на её месте будет валидная с точки зрения формата заглушка. Такая информация обозначена следующим образом: [личная информация].

Полный ответ имеет большой размер, поэтому реализован следующий механизм его сжатия:

  • в параметре client_turns можно передать список номеров ходов (через запятую), для которых на клиенте есть полная информация;
  • если сервер сможет, в ответе он вернёт только изменившуюся информацию о герое;
  • сокращению подвергается только информация в <hero_info>;
  • сокращение происходит удалением неизменившихся полей (только на верхнем уровне, без рекурсии);
  • чтобы получить полную информацию, скопируйте недостаующие поля из закэшированной на стороне клиента информации для хода, указанного в .account.hero.patch_turn;
  • сервер не гарантирует, что вернёт сокращённую информацию;
  • сервер может вернуть патч для любого из переданных в client_turns ходов;
  • имеет смысл в параметре client_turns передавать последние 2-3 хода;
  • обратите внимание, сжатие ответа применяется и к информации о противнике в PvP! Поэтому первый запрос при PvP всегда должен требовать полную информацию.

Формат данных в ответе:

{
  "mode": "pve"|"pvp",             // режим героя
  "turn": {                        // информация о номере хода
    "number": <целое число>,       // номер хода
    "verbose_date": "строка",      // дата для игроков (в мире Сказки)
    "verbose_time": "строка"       // время для игроков (в мире Сказки)
  },
  "game_state": <целое число>,     // состояние игры (остановлена/запущена, см. в описании API)
  "map_version": "строка",         // версия актуальной карты игры
  "account": <account_info>|null,  // информация о запрашиваемом аккаунте и герое
  "enemy": <account_info>|null     // информация о противнике, если идёт pvp сражение
}

<account_info> = {
  "new_messages": <целое число>, // количество личных сообщений
  "id": <целое число>,           // идентификатор аккаунта
  "last_visit": <timestamp>,     // примерное время последнего посещения игры
  "is_own": true|false,          // информация о собственном герое или о чужом
  "is_old": true|false,          // информация устаревшая или нет
  "hero": <hero_info>,           // информация о герое
  "in_pvp_queue": true|false     // находится ли герой в очереди на арену
}

<hero_info> = {
  "patch_turn": null|<целое число>,  // номер хода, для которого возвращается патч или null, если информация полная

  "energy":{                      // энергия игрока [личная информация]
        "bonus": <целое число>,   // дополнительная энергия
        "max": <целое число>,     // максимальное количество
        "value": <целое число>,   // текущее количество
        "discount": <целое число> // скидка энергии при её трате (например, от использования артефактов)
  },

  "equipment":{                      // экипировка героя, словарь <идентификатор типа экипировки, информация об артефакте>
    "<целое число>": <artifact_info> // идентификатор типа экипировки: информация об артефакте
  },

  "cards":{                          // карты судьбы [личная информация]
    "cards": [                       // список карт
      <card_info>                    // информация о карте
    ],
    "help_count": <целое число>,     // сколько помощи накоплено для получения новой карты
    "help_barrier": <целое число>    // сколько всего помощи надо накопить для новой карты
  },

  "companion": <companion_info>|null,// информация о спутнике

  "bag":{                            // содержимое рюкзака, словарь <внутренний идентификатор предмета, описание> ()
    "<целое число>": <artifact_info> // идентификатор слота: информация об артефакте
  },

  "base":{                                // базовые параметры героя
    "experience": <целое число>,          // текущий опыт
    "race": <целое число>,                // раса
    "health": <целое число>,              // здоровье
    "name": "строка",                     // имя героя
    "level": <целое число>,               // уровень героя
    "gender": <целое число>,              // пол
    "experience_to_level": <целое число>, // абсолютное количество опыта до следующего уровня
    "max_health": <целое число>,          // максимальное количество здоровья
    "destiny_points": <целое число>       // сколько способностей сейчас может выбрать
    "money": <целое число>,               // количество денег у героя
    "alive": true|false,                  // жив герой или мёртв
  },

  "secondary":{                              // второстепенные параметры
    "max_bag_size": <целое число>,           // максимальный размер рюкзака
    "power": [<целое число>, <целое число>], // физическая сила, магическая сила
    "move_speed": <дробное число>,           // скорость движения
    "loot_items_count": <целое число>,       // количество лута в рюкзаке
    "initiative": <дробное число>            // инициатива героя
  },

  "diary": "строка",       // версия дневника героя, если она изменилась, необходимо перезапросить дневни

  "messages":[             // сообщения из журнала
    [                      // запись в задании
      <timestamp>,         // timestamp создания сообщения
      "строка",            // текстовое описание времени в игре
      "строка",            // текст
      <целое число>|null,  // идентификатор типа фразы, найти идентификатор типа фразы можно в адресе страницы лингвистики с фразами этого типа
      {"строка": "строка"} // словарь соотношения переменных и их значений (ВНИМАНИЕ! перечень переменных может изменяться без изменения версии этого метода)
    ]
  ],

  "habits": { // черты
    "строка": {              // идентификатор черты
      "verbose": "строка",   // текущее текстовое значение черты для игрока (название характера)
      "raw": <дробное число> // текущее числовое значение черты
    }
  },

  "quests": {     // информация о заданиях
    "quests": [   // список глобальных заданий
      {
        "line": [ // список «базовых» заданий (цепочка последовательных заданий)
           {
             "type": "строка",            // тип задания
             "uid":  "строка",            // уникальный идентификатор задания
             "name": "строка",            // название задания
             "action": "строка",          // описание текущего действия героя в задании
             "choice": "строка"|null,     // текущий выбор героя в задании
             "choice_alternatives": [     // альтернативные выборы
               [
                 "строка",                // уникальный идентификатор выбора
                 "строка"                 // текстовое описание выбора
               ]
             ],
             "experience": <целое число>, // количество опыта за задание
             "power": <целое число>,      // количество влияния за задание
             "actors": [                  // список «актёров», участвующих в задании
               [
                 "строка",                // название актёра
                 <целое число>",                // тип актёра (список типов приведён в описании API)
                 <quest_actor_info>       // данные, специфичные для конкретного типа актёра
               ]
             ]
           }
        ]
      }
    ]
  },

  "action":{                     // текущее действие
    "percents": <дробное число>, // процент выполнения
    "description": "строка",     // описание
    "info_link": "url"|null      // ссылка на доп. информацию
    "type": <целое число>        // идентификатор типа действия
    "data": null|<словарь>       // дополнительная информация о действиии или null, если такой нет
  },

  "position":{                      // позиция героя на клеточной карте
    "x": <дробное число>,           // координата x
    "y": <дробное число>,           // координата y
    "dx": <дробное число>,          // направление взгляда по x
    "dy": <дробное число>,          // направленеи взгляда по y
  },

  "permissions": {                        // права на выполнение различных операций
    "can_participate_in_pvp": true|false, // может ли участвовать в pvp
    "can_repair_building": true|false,    // может ли чинить здания
  },

  "might": {                                    // могущество игрока
    "value": <дробное число>,                   // величина
    "crit_chance": <дробное число>,             // вероятность критического срабатывания помощи
    "pvp_effectiveness_bonus": <дробное число>, // бонус к эффективности в pvp от могущества
    "politics_power": <дробное число>            // бонус к политическому влиянию героя
  },

  "id": <целое число>,                             // идентификатор
  "actual_on_turn": <целое число>,                 // данные на какой ход предоставлены

  "sprite": <целое число>  // идентификатор спрайта, которым отображается герой
  }

<quest_actor_info> = <quest_actor_place_info>|<quest_actor_person_info>|<quest_actor_spending_info>

<quest_actor_place_info> = { // информация о городе
  "id": <целое числое>,      // идентификатор
  "name": "строка"           // название города
}

<quest_actor_person_info> = {     // информация о жителе города
    "id": <целое числое>          // идентификатор
    "name": "строка",             // имя
    "race": <целое числое>,       // раса
    "gender": <целое числое>,     // пол
    "profession": <целое числое>, // профессия
    "mastery_verbose": "строка",  // профессия
    "place": <целое числое>       // идентификатор города
}

<quest_actor_spending_info> = { // информация о целях накопления
  "goal": "строка"              // описание цели накопления
}

<artifact_info> = {                              // информация об артефакте
    "name": "строка",                            // название
    "power": [<целое число>, <целое число>],     // сила [физическая, магическая]
    "type": <целое число>,                       // тип
    "integrity": [<целое число>, <целое число>], // целостность [текущая, максимальная]
    "rarity": <целое число>,                     // редкость
    "effect": <целое число>,                     // тип эффекта на артефакте
    "special_effect": <целое число>,             // тип особого свойства артефакта (эффекта, который действует независимо от редкости)
    "preference_rating": <дробное число>,        // «полезность» артефакта с точки зрения героя
    "equipped": true|false,                      // может ли быть экипирован
    "id": <целое число>                          // уникальный идентификатор рода артефакта
}

<card_info> = {                              // информация о карте в колоде игрока
    "name": "строка",                        // название
    "type": <целое число>,                   // тип
    "rarity": <целое число>,                 // редкость карты
    "uid": <целое число>,                    // уникальный идентификатор в колоде игрока
    "auction": true|false                    // может быть продана на рынке
}

<companion_info> = {                         // информация о спутнике героя
    "type": <целое число>,                   // тип спутника
    "name": "строка",                        // название/имя спутника
    "health": <целое число>,                 // текущее здоровье
    "max_health": <целое число>,             // максимальное здоровье
    "experience": <целое число>,             // текущий опыт слаженности
    "experience_to_level": <целое число>,    // опыта до следующего уровня слаженности
    "coherence": <целое число>,              // текущая слаженность
    "real_coherence": <целое число>          // полная слаженность (без учёта ограничений на максимум слаженности)
}

примечания:

  • если информация о герое устаревшая (is_old == true), то следует повторить запрос через несколько секунд (но лучше не злоупотреблять)

Дневник героя

Информация о дневнике героя

  • адрес: /game/api/diary
  • http-метод: GET
  • версии: 1.0
  • параметры: нет
  • возможные ошибки: нет

Формат данных в ответе:

{
    "version": <целое>,                       // версия дневника
    "messages": [                             // список последних сообщений в дневнике
       {                                      // запись в дневнике
          "timestamp": <timestamp>,           // timestamp создания сообщения
          "game_time": "строка",              // текстовое описание времени в игре
          "game_date": "строка",              // текстовое описание даты в игре
          "message": "строка",                // текст
          "type": <целое число>|null,         // идентификатор типа фразы, найти идентификатор типа фразы можно в адресе страницы лингвистики с фразами этого типа
          "variables": {"строка": "строка"},  // словарь соотношения переменных и их значений (ВНИМАНИЕ! перечень переменных может изменяться без изменения версии этого метода)
          "position": "строка"                // текстовое описание места, где герой находился во время создания записи
        }
    ]
}

Использование способности

Использование одной из способностей игрока (список способностей см. в разделе типов)

  • адрес: /game/abilities/<идентификатор способности>/api/use
  • http-метод: POST
  • версии: 1.0
  • параметры:
    • GET: building — идентификатор здания, если способность касается здания
    • GET: battle — идентификатор pvp сражения, если способность касается операций с pvp сражением
  • возможные ошибки: нет

Метод является «неблокирующей операцией» (см. документацию), формат ответа соответствует ответу для всех «неблокирующих операций».

Цена использования способностей возвращается при запросе базовой информации.

Выбор в задании

Изменение пути выполнения задания героем

  • адрес: /game/quests/api/choose/
  • http-метод: POST
  • версии: 1.0
  • параметры:
    • GET: option_uid — уникальный идентификатор выбора в задании (получается с информацией о состоянии игры)
  • возможные ошибки: нет

Метод является «неблокирующей операцией» (см. документацию), формат ответа соответствует ответу для всех «неблокирующих операций».

Карты: взять

Взять новую карту в колоду игрока.

  • адрес: /game/cards/api/get
  • http-метод: POST
  • версии: 1.0
  • параметры: нет
  • возможные ошибки: нет

Метод является «неблокирующей операцией» (см. документацию), формат ответа соответствует ответу для всех «неблокирующих операций».

При завершении операции возвращается дополнительная инфрмация:

{
  "message": "строка",      // описание результата в формате html
  "card": <card_info>       // описание полученной карты, формат см. в описании формата информации о герое
}

Карты: объединить

Объединить карты из колоды игрока.

  • адрес: /game/cards/api/combine
  • http-метод: POST
  • версии: 1.0
  • параметры:
    • GET: cards — перечень уникальный идентификаторов карт в колоде игрока через запятую
  • возможные ошибки:
    • cards.api-combine.wrong_cards — указанные карты нельзя объединить

Метод является «неблокирующей операцией» (см. документацию), формат ответа соответствует ответу для всех «неблокирующих операций».

При завершении операции возвращается дополнительная инфрмация:

{
  "message": "строка",      // описание результата в формате html
  "card": <card_info>       // описание полученной карты, формат см. в описании формата информации о герое
}

Карты: использовать

Использовать карту из колоды игрока.

  • адрес: /game/cards/api/use
  • http-метод: POST
  • версии: 1.0
  • параметры:
    • GET: card — уникальный идентификатор карты в калоде
    • POST: person — идентификатор Мастера, если карта применяется к Мастеру
    • POST: place — идентификатор города, если карта применяется к городу
    • POST: building — идентификатор здания, если карта применяется к зданию
  • возможные ошибки:
    • cards.use.form_errors — ошибка в одном из POST параметров

Метод является «неблокирующей операцией» (см. документацию), формат ответа соответствует ответу для всех «неблокирующих операций».

Города: перечень всех городов

Получить перечень всех городов с их основными параметрами

  • адрес: /game/places/api/list
  • http-метод: GET
  • версии: 1.1
  • параметры: нет
  • возможные ошибки: нет

При завершении операции возвращается следующая информация:

{
  "places": {                 // перечень всех городов
    "<целое число>": {        // идентификатор города: информация о нём
      "id": <целое число>,    // идентификатор города
      "name": "строка",       // название города
      "frontier": true|false, // находится ли город на фронтире
      "position": { "x": <целое число>,   // координаты города на карте
                    "y": <целое число> }, // (могут меняться при изменении размера карты!)
      "size": <целое число>,              // размер города
      "specialization": <целое число>     // идентификатор специализации
    }
  }
}

Города: подробная информация о городе

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

  • адрес: /game/places/<place>/api/show
  • http-метод: GET
  • версии: 2.0
  • параметры:
    • URL place — идентификатор города
  • возможные ошибки: нет

Это экспериментальный метод, при появлении новой версии не гарантируется работоспособность предыдущей!

При завершении операции возвращается следующая информация:

{
  "id": <целое число>,        // идентификатор города
  "name": "строка",           // название города
  "frontier": true|false,     // является ли город фронтиром
  "new_for": <timestamp>,     // время, до которого город считается новым
  "updated_at": <timestamp>,  // время последнего обновления информации
  "description": "строка",    // описание города

  "position": {"x": <целое число>, "y": <целое число>},   // координаты города

  "politic_power": <politic_power>,            // политическое влияние города
  "persons": <persons_info>,                   // Мастера
  "attributes": <attributes_info>,             // все параметры города
  "demographics": <demographics_info>,         // расовый состав
  "bills": <bills_info>,                       // действующие законы
  "habits": <habits_info>,                     // черты города
  "chronicle": <chronicle_info>,               // последние записи в летописи
  "accounts": <accounts_info>,                 // краткая дополнительная информация об игроках, связанных с городом
  "clans": <clans_info>                        // краткая дополнительная информация о кланах, связанных с городом
}

<politic_power> = {
    "power": {
        "inner": { "value": <дробное число>,            // суммарное влияние ближнего круга
                   "fraction": <дробное число> },       // доля среди остальных городов
                                                        // (Фронтир и Ядро считаются отдельно)

        "outer": { "value": <дробное число>,            // суммарное влияние «толпы»
                   "fraction": <дробное число> },       // доля среди остальных городов
                                                        // (Фронтир и Ядро считаются отдельно)

        "fraction": <дробное число>                     // доля общего влияния среди остальных городов
                                                        //(Фронтир и Ядро считаются отдельно)
    },
    "heroes": {                                         // влияющие на город герои (ближний круг и кандидаты в него)
        "positive": {"<целое число>": <дробное число>}, // позитивное влияние <идентификатор героя, принесённое влияние>
        "negative": {"<целое число>": <дробное число>}, // негативное влияние <идентификатор героя, принесённое влияние>
    }
}

<persons_info> = [
   { "id": <целое число>,                       // идентификатор Мастера
     "name": "строка",                          // имя
     "gender": <целое число>,                   // пол
     "race": <целое число>,                     // раса
     "type": <целое число>,                     // профессия
     "next_move_available_in": <дробное число>, // количество секунда до момента, когда Мастер может переехать в другой город
     "politic_power_fraction": <дробное число>, // доля влияния в городе
     "building": {                              // информация о здании, если оно есть
         "id": <целое число>,                   // идентификатор
         "position": {"x": <целое число>,       // позиция
                      "y": <целое число>},      //
         "type": <целое число>,                 // тип, значения перечислены на странице API
         "integrity": <дробное число>,          // целостность здания от 0.0 до 1.0
         "created_at_turn": <целое число>,      // номер хода на котором создано
         "repair_number": <целое число>         // сколько починок необходимо до полность целостности
     } | null,
     "personality": {                           // характер
         "cosmetic": <целое число>,             // идентификатор косметической особенности характера
         "practical": <целое число>             // идентификатор практической особенности характера
     }
   },
   …
]

<attributes_info> = {                                // информация о всех параметрах города
    "effects": [                                     // эффекты, действующие на город
        { "name": "<строка>",                        // название эффекта
          "attribute": <целое число>,                // на какой аттрибут влияет
          "value": <целое>|<дробное>|"<строка>"|null // значение, null, если значение комплексное и пока не сериализуется в API
        },
        ...
    ],
    "attributes": [                                  // итоговые значения аттрибутов
        { "id": <целое число>,                       // идентификатор аттрибута
          "value": <целое>|<дробное>|"<строка>"|null // значение, null, если значение комплексное и пока не сериализуется в API
        }
    ]
}

<demographics_info> = [
  { "race": <целое число>,       // раса
    "percents": <дробное число>, // текущая доля (от 0 до 1)
    "delta": <дробное число>,    // изменение в день
    "persons": <дробное число>}, // влияние Мастеров (от 0 до 1)
  …
]

<bills_info> = [
  { "id": <целое число>,           // идентификатор закона
    "caption": "строка",           // название закона
    "properties": ["строка", …] }, // перечень описаний эффектов закона на город
  …
]

<habits_info> = {  // информация о каждой черте города в формате "идентификатор черты": {информация о черте}
  "<целое число>": {"interval": <целое число>,             // идентификатор текущего «уровня» черты
                    "value": <дробное число>,              // текущее абсолютное значенеи черты
                    "delta": <дробное число>,              // величина изменения черты за один час
                    "positive_points": <дробное число>,    // суммарное позитивное влияние героев на черту города
                    "negative_points": <дробное число> },  // суммарное негативное влияние героев на черту города
  …
}

<chronicle_info> = [("строка", "строка", "строка"), …] // последние записи из летописи о городе в формате ("короткая дата", "длинная дата", "текст")

<accounts_info> = {
  "<целое число>": {            // идентификатор игрока
    "id": <целое число>,        // идентификатор игрока
    "name": "строка",           // ник
    "hero": {                   // краткая информация о герое
      "id": <целое число>,      // идентификатор
      "name": "строка",         // имя
      "race": <целое число>,    // раса
      "gender": <целое число>,  // пол
      "level": <целое число> }, // уровень
    "clan": <целое число>|null  // идентификатор клана
  },
  …
}

<clans_info> = {
 "<целое число>": {     // идентификатор клана
   "id": <целое число>, // идентификатор клана
   "abbr": "строка",    // аббревиатура
   "name": "строка"},   // полное название
 …
}

Мастера: подробная информация о Мастере

Подробная информация о конкретном Мастере

  • адрес: /game/persons/<person>/api/show
  • http-метод: GET
  • версии: 1.0
  • параметры:
    • URL person — идентификатор Мастера
  • возможные ошибки: нет

Это экспериментальный метод, при появлении новой версии не гарантируется работоспособность предыдущей!

При завершении операции возвращается следующая информация:

{
  "id": <целое число>,        // идентификатор Мастера
  "name": "строка",           // имя
  "updated_at": <timestamp>,  // время последнего обновления информации

  "place": {                           // краткая информация о городе
      "id": <целое число>,             // идентификатор
      "name": "<строка>",              // название
      "size": <целое число>,           // размер
      "specialization": <целое число>, // специализация
      "position": {                    // координаты
          "x": <целое число>,
          "y": <целое число> }
  },

  // формат следующих параметров такой же, как в методе получения информации о городе

  "building": <словарь>|null,          // информация о зданиии, если оно есть
  "politic_power": <politic_power>,    // политическое влияние
  "attributes": <attributes_info>,     // все параметры Мастера
  "chronicle": <chronicle_info>,       // последние записи в летописи
  "accounts": <accounts_info>,         // краткая дополнительная информация об игроках, связанных с Мастером
  "clans": <clans_info>                // краткая дополнительная информация о кланах, связанных с Мастером
}

Типы

Артефакты: редкость

значение описание
0 обычный артефакт
1 редкий артефакт
2 эпический артефакт

Артефакты: типы

значение описание
0 хлам
1 основная рука
2 вторая рука
3 доспех
4 амулет
5 шлем
6 плащ
7 наплечники
8 перчатки
9 штаны
10 обувь
11 кольцо

Артефакты: типы экипировки

значение описание
0 основная рука
1 вспомогательная рука
2 шлем
9 амулет
3 наплечники
4 доспех
5 перчатки
6 плащ
7 штаны
8 сапоги
10 кольцо

Артефакты: эффекты

значение описание
0 мощь
1 колдовство
2 хорошая реакция
3 здоровье
4 повышение интуиции
5 хитрость
6 астральный сосуд
7 скороход
8 карманы
666 нет эффекта
1000 небывалая мощь
1001 могучее колдовство
1002 превосходная реакция
1003 невероятное здоровье
1004 сверхинтуиция
1005 особая хитрость
1006 большой астральный сосуд
1007 неутомимый скороход
1008 большие карманы
1009 выносливость
1010 живучесть
1011 деятельность
1012 убеждение
1013 очарование
1014 духовная связь
1015 душевное равновесие
1016 особая аура
1017 регенерация
1018 последний шанс
1019 лёд
1020 пламя
1021 яд
1022 вампиризм
1023 живость ума
1024 ужасный вид
1025 точные атаки
1026 астральная преграда
1027 затуманенный разум
1028 удача странника
1029 удача героя
1030 крепость духа
1031 идейность
1032 нерушимость
1033 ускорение
1034 безрассудность
100001 детский подарок

Карты: типы

значение описание
1 озарение
5 капля энергии
6 чаша Силы
7 магический вихрь
8 энергетический шторм
9 шквал Силы
10 горсть монет
11 увесистый кошель
12 сундучок на счастье
13 умеренность
14 чревоугодие
15 спокойствие
16 вспыльчивость
17 верность
18 блуд
19 дружелюбие
20 алчность
21 скромность
22 тщеславие
23 сдержанность
24 гнев
25 смирение
26 гордыня
27 миролюбие
28 ярость
29 знание врага
30 новая родина
31 новый соратник
32 новый противник
33 прозрение
34 вкусы в экипировке
35 определение лихости
36 наскучившая вещь
37 пересмотр стиля боя
38 пересмотр ценностей
39 альтернатива
40 странный зуд
41 магазинный импульс
42 стремление к совершенству
43 тяга к знаниям
44 забота об имуществе
45 фея-мастерица
46 благословение Великого Творца
47 другие заботы
48 внезапная находка
49 полезный подарок
50 редкое приобретение
51 дар Хранителя
52 длань Смерти
53 неразменная монета
54 волшебный горшочек
55 скатерть самобранка
56 несметные богатства
0 рог изобилия
57 волшебный инструмент
58 удачный день
59 нежданная выгода
60 удачная афера
61 преступление века
62 погожие деньки
63 торговый день
64 городской праздник
65 экономический рост
66 ужасная погода
67 запустение
68 нашествие крыс
69 экономический спад
70 ошибка в архивах
71 фальшивые рекомендации
72 застолье в Совете
73 интриги
74 удачная мысль
75 чистый разум
76 неожиданные осложнения
77 слово Гзанзара
78 новые обстоятельства
79 специальная операция
80 слово Дабнглана
81 благословение Дабнглана
82 телепорт
83 ТАРДИС
84 амнезия
85 донор Силы
86 взыскание долга
87 ритуал Силы
88 волшебное точило
89 суть вещей
90 обычный спутник
91 необычный спутник
92 редкий спутник
93 эпический спутник
94 легендарный спутник
95 новый взгляд
96 чуткость
97 благословение Гзанзара
98 новый путь
99 четыре стороны
100 передышка
101 подорожник
102 священный мёд
103 молодильное яблоко
104 живая вода
105 забота о ближнем
106 скрытый потенциал
107 туз в рукаве
108 улыбка фортуны
109 выгодный контракт
110 сорванный контракт
111 гримаса фортуны
112 гадкий день
113 нежданная беда
114 провальное мероприятие
115 чёрная полоса

Карты: редкость

значение описание
0 обычная карта
1 необычная карта
2 редкая карта
3 эпическая карта
4 легендарная карта

Герои: тип действия

значение описание
0 герой бездельничает
1 герой выполненяет задание
2 герой путешествует между городами
3 герой сражается 1x1 с монстром
4 герой воскресает
5 герой в городе
6 герой лечится
7 герой экипируется
8 герой торгует
9 герой путешествует около города
10 герой восстановливает энергию Хранителю
11 техническое действие для особых действий героя в заданиях
12 техническое прокси-действие для взаимодействия героев
13 герой сражается 1x1 с другим героем
14 техническое действие для тестов
15 герой ухаживает за спутником
16 действия героя сразу после иницииации (новый герой создан для нового игрока)

Города: специализация

значение описание
0 Торговый центр
1 Город мастеров
2 Форт
3 Политический центр
4 Полис
5 Курорт
6 Транспортный узел
7 Вольница
8 Святой город
9 Обычный город

Города: аттрибуты

значение описание
0 размер города
2 радиус изменений
3 радиус владений
4 производство
5 товары
6 дары Хранителей
7 безопасность
8 транспорт
9 свобода
10 пошлина
11 стабильность
12 восстановление стабильности
13 бонус к опыту
14 цена покупки предметов
15 цена продажи предметов
16 сила покупаемых артефактов
19 восстановление энергии
20 лечение героя
21 лечение спутника
22 экономика
23 специализация «Торговый центр»
24 специализация «Город мастеров»
25 специализация «Форт»
26 специализация «Политический центр»
27 специализация «Полис»
28 специализация «Курорт»
29 специализация «Транспортный узел»
30 специализация «Вольница»
31 специализация «Святой город»
32 сила специализаций
33 культура

Задания: типы актёров

значение описание
0 житель
1 место
2 трата денег

Здания: типы

значение описание
0 кузница
1 домик рыболова
2 мастерская портного
3 лесопилка
4 домик охотника
5 сторожевая башня
6 торговый пост
7 трактир
8 логово вора
9 ферма
10 шахта
11 храм
12 больница
13 лаборатория
14 плаха
15 башня мага
16 ломбард
17 бюро
18 цех
19 сцена
20 конюшни
21 ранчо

Игрок: тип способности

значение описание атрибуты запроса
help Помочь ()
arena_pvp_1x1 Отправить на арену ()
arena_pvp_1x1_leave_queue Выйти из очереди ()
arena_pvp_1x1_accept Принять вызов ('battle',)
building_repair Вызвать рабочего ('building',)
drop_item Выбросить предмет ()

Общее: пол

значение описание
0 мужчина
1 женщина
2 оно

Общее: раса

значение описание
0 человек
1 эльф
2 орк
3 гоблин
4 дварф

Общее: черты

значение целое значение строковое описание
0 honor честь
1 peacefulness миролюбие

Общее: честь

значение для героя для города
0 бесчестный криминальная столица
1 подлый бандитская вотчина
2 порочный неблагополучный город
3 себе на уме обычный город
4 порядочный благополучное поселение
5 благородный честный город
6 хозяин своего слова оплот благородства

Общее: миролюбие

значение для героя для города
0 скорый на расправу территория вендетт
1 вспыльчивый пристанище горячих голов
2 задира беспокойное место
3 сдержанный неприметное поселение
4 доброхот спокойное место
5 миролюбивый мирное поселение
6 гуманист центр цивилизации

Прочее: состояние авторизации

значение описание
0 авторизация не запрашивалась
1 пользователь ещё не принял решение
2 авторизация прошла успешно
3 в авторизации отказано

Прочее: состояние игры

значение описание
0 остановлена
1 запущена

Мастер: профессия

значение описание
0 кузнец
1 рыбак
2 портной
3 плотник
4 охотник
5 стражник
6 торговец
7 трактирщик
8 вор
9 фермер
10 шахтёр
11 священник
12 лекарь
13 алхимик
14 палач
15 волшебник
16 ростовщик
17 писарь
18 магомеханик
19 бард
20 дрессировщик
21 скотовод

Мастер: тип социальной связи

значение описание
0 партнёр
1 конкурент

Мастер: косметические особенности характера

значение описание
0 правдолюб
1 плут
2 добряк
3 забияка
4 лидер
5 непоседа
6 поручитель
7 нигилист
8 затворник
9 организатор

Мастер: практические особенности характера

значение описание
1 многомудрый
2 влиятельный
3 щедрый
4 харизматичный
5 мстительный
6 деятельный
7 надёжный
8 аккуратный
9 набожный
10 трудолюбивый
11 предприимчивый
12 романтичный
13 ответственный
14 коварный

Общие ошибки

В этом разделе перечислены ошибки, которые могут возникнуть при вызове любого (или почти любого) метода.

  1. api.no_method_version — не указана версия метода
  2. api.no_client_indentificator — не указана версия клиента
  3. api.wrong_client_identificator_format — неверный формат идентификатора клиента
  4. api.wrong_method_version — неверная версия метода
  5. common.login_required — необходимо войти в игру
  6. common.staff_required — необходимы права администратора
  7. common.superuser_required — необходимы права суперпользователя
  8. third_party.access_restricted — доступ к функциональности запрещён сторонним приложениям. Необходимо авторизоваться с помощью логина/пароля.