Методы

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

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

адрес:

/api/info/

http-метод:

GET

версии:

1.1

параметры:

нет

ошибки:

нет

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

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

Абсолютные адреса возвращаются без указания протокола: //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>, // адрес, на который необходимо направить пользователя для подтверждения авторизации
}

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

  1. приложение делает запрос к этому методу;

  2. в ответе приходит ссылка, по которой надо направить пользователя, и устанавливается значение cookie с именем sessionid, которое и является идентификатором сессии пользователя;

  3. пользователь переходит по ссылке, на странице у него спрашивают разрешение на доступ к своим данным для данного приложения;

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

  5. ответ метода будет содержать информацию о статусе авторизации и о пользователе;

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

Значение cookie с именем sessionid будет изменено сервером при первом запросе к нему после того как пользователь подтвердил разрешение (скорее всего это будет запрос состояния авторизации). После этого необходимо будет использовать установленное сервером значение cookie.

Запрос авторизации не хранится вечно, гарантируется его доступность в течение 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)
  "clan": null | {                // информация о гильдии, null, если в гильдии не состоит
     "id": <целое>,               // идентификатор
     "abbr": "строка",            // аббревиатура
     "name": "строка"             // название
  }
}

Количество новых сообщений

Получить количество новых сообщений для игрока.

адрес:

/accounts/messages/api/new-messages-number

http-метод:

GET

версии:

0.1

параметры:

нет

ошибки:

нет

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

{
  "number": <целое число> // количество новых сообщений
}

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

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

адрес:

/game/api/info

http-метод:

GET

версии:

1.10

параметры:
  • GET: account — идентификатор аккаунта

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

ошибки:

нет

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

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

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

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

  • в параметре client_turns можно передать список номеров ходов (через запятую), для которых на клиенте есть полная информация;

  • если сервер сможет, в ответе он вернёт только изменившуюся информацию о герое;

  • сокращению подвергается только информация в hero_info;

  • сокращение происходит удалением неизменившихся полей 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>            // информация о герое
}

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

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

  "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": <дробное число>,                   // величина
    "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": <целое число>                          // уникальный идентификатор рода артефакта
}

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

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

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

адрес:

/game/api/diary

http-метод:

GET

версии:

1.0

параметры:

нет

ошибки:

нет

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

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

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

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

адрес:

/game/quests/api/choose/

http-метод:

POST

версии:

1.0

параметры:
  • GET: option_uid — уникальный идентификатор выбора в задании (получается с информацией о состоянии игры)

ошибки:

нет

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

Карты: получить новые карты

Получить все накопившиеся новые карты.

адрес:

/game/cards/api/receive

http-метод:

POST

версии:

1.0

параметры:

нет

ошибки:

нет

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

{
  "cards": [
      <card_info>, // описание полученной карты
      ...]
}

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

Карты: превратить

Превратить карты из колоды игрока.

адрес:

/game/cards/api/combine

http-метод:

POST

версии:

3.0

параметры:
  • POST: card — идентификатор карты, участвующей в трансформации, может быть несколько

ошибки:
  • cards.combine.wrong_cards — указанные карты нельзя превращать

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

{
  "message": "строка",  // описаниеb результата в формате html
  "cards": [
      <card_info>,      // описание полученной карты, формат см. в описании метода получения новой карты
      // …
      ]
}

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

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

адрес:

/game/cards/api/use

http-метод:

POST

версии:

2.0

параметры:
  • GET: card — уникальный идентификатор карты в калоде

  • POST: value — параметр использования карты, если у карты есть параметр, обычно это идентификатор объекта (Мастера, города, etc)

  • POST: name — название гильдии для карты создания гильдии

  • POST: abbr — аббревиатура гильдии для карты создания гильдии

ошибки:
  • cards.use.form_errors — ошибка в одном из POST параметров

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

Карты: перечень карт игрока

Возвращает список всех карт игрока.

адрес:

/game/cards/api/get-cards

http-метод:

GET

версии:

2.0

параметры:

нет

ошибки:

нет

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

{
  "cards": [
      <card_info>,       // описание полученной карты, формат см. в описании метода получения новой карты
      ...
   ],
  "new_cards": <целое число>,       // количество новых карт, которые можно получить

  "new_card_timer": {               // таймер, отсчитывающий время получения следующей карт
      "speed": <дробное число>,     // скорость накопления ресурсов (в секунду)
      "border": <дробное число>,    // сколько «ресурсов» надо накопить, чтобы сработал таймер
      "resources": <дробное число>, // количество ресурсов, которые накопились к моменту resources_at
      "resources_at": <timestamp>,  // время, на которое указано количество «ресурсов» в resources
      "finish_at": <timestamp>      // время срабатывания таймера
  }
}

Карты: переместить в хранилище

Перемещает карты в хранилище.

адрес:

/game/cards/api/move-to-storage

http-метод:

POST

версии:

2.0

параметры:
  • POST: card — идентификатор перемещаемой карты, может быть несколько

ошибки:
  • card.wrong_value — указанные карты нельзя превращать

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

{
}

Карты: переместить в руку

Перемещает карты в руку.

адрес:

/game/cards/api/move-to-hand

http-метод:

POST

версии:

2.0

параметры:
  • POST: card — идентификатор перемещаемой карты, может быть несколько

ошибки:
  • card.wrong_value — указанные карты нельзя превращать

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

{
}

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

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

адрес:

/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.3

параметры:
  • 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": {                                         // влияющие на город герои (ближний круг и кандидаты в него)
        "size": <целое число>,                          // количество героев сверху списка, на которых может действовать проект
        "rating": [[<целое число>, <дробное число>],    // перечень героев ближнего круга с влиянием <id героя, влияние>
                   //…
                  ]
    }
}

<persons_info> = [
   { "id": <целое число>,                       // идентификатор Мастера
     "name": "строка",                          // имя
     "gender": <целое число>,                   // пол
     "race": <целое число>,                     // раса
     "type": <целое число>,                     // профессия
     "next_move_available_in": <дробное число>, // количество секунда до момента, когда Мастер может переехать в другой город
     "politic_power_fraction": <дробное число>, // доля влияния в городе
     "building": {                              // информация о здании, если оно есть
         "id": <целое число>,                   // идентификатор
         "position": {"x": <целое число>,       // позиция
                      "y": <целое число>},      //
         "type": <целое число>,                 // тип, значения перечислены на странице API
         "created_at_turn": <целое число>,      // номер хода на котором создано
     } | 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": <целое число>,                 // пол
      "power": [<целое число>, <целое число>], // физическая сила, магическая сила
      "level": <целое число> },                // уровень
    "clan": <целое число>|null  // идентификатор клана
  },
  ...
}

<clans_info> = {
 "<целое число>": <clan_info>  // <идентификатор клана, информация о клане>
 ...
}

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

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

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

адрес:

/game/persons/<person>/api/show

http-метод:

GET

версии:

1.2

параметры:
  • URL person — идентификатор Мастера

ошибки:

нет

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

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

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

  "profession": <целое число>,  // профессия
  "race": <целое число>,        // раса
  "gender": <целое число>,      // пол

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

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

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

<job_info> = {
  "name": "строка",                 // название проекта
  "effect": <целое число>,          // тип эффекта по завершению проекта
  "positive_power": <целое число>,  // накопленное положительное влияние
  "negative_power": <целое число>,  // накопленное отрицательное влияние
  "power_required": <целое число>   // требуемое влияние
}

Карта: получить карту

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

адрес:

/game/map/api/region

http-метод:

GET

версии:

0.1

параметры:
  • GET: turn - целое, номер хода, на который необходимо получить карту

ошибки:
  • no_region_found - для заданного хода нет сохранённых данных

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

{
    "turn": <целое>,                // номер хода, на котором была создана эта версия карты
    "region": {                     // описание карты
        "format_version": "строка", // версия формата
        "map_version": "строка",    // уникальный идентификатор этой версии карты
        "width": <целое>,           // размер карты по ширине
        "height": <целое>,          // размер карты по высоте

        "draw_info":           // инструкция по отрисовке
        [                      // строки карты
            [                  // столбцы карты
                [              // список спрайтов конкретной клетки
                    [<целое>,  // идентикаитор спрайта
                     <целое>], // идентификатор поворота:
                               // 0 — 0 градусов
                               // 1 — 90 градусов
                               // 2 — 180 градусов
                               // 3 — 270 градусов
                    ...
                ]
            ]
        ],

        "places": {                    // перечень городов
            "<целое>": {               // идентификатор города
                "name": "строка",      // название
                "race": <целое>,       // раса
                "pos": {"y": <целое>,  // координаты клетки на карте
                        "x": <целое>},
                "id": <целое>,         // идентификатор города
                "size": <целое>,       // размер
                "clan_protector": null|<clan_info> // информация о клане-протекторе города, если он есть
            }
        },
        "roads": {                     // перечень дорог
            "<целое>": {
                "point_1_id": <целое>, // из каого объекта (города) идёт дорога
                "point_2_id": <целое>, // в какой объект (город) идёт дорога
                "id": <целое>,         // идентификатор дороги
                "exists": true|false,  // видим ли дорога на карет
                "length": <дробное>,   // длинна дороги
                "path": "строка"       // путь из точки 1 в точку 2 по клеткам, последовательность символов:
                                       // l — left — влево
                                       // r — right — вправо
                                       // u — up — вверх
                                       // d — down — вниз
            }
        }
    }
}

Актуальный список спрайтов можено найти в константах браузерного клиента.

Более удобное описание спрайтов можно найти в python коде

Карта: получить список версий карт

Список ходов, для которых есть соответствующая версия карты.

адрес:

/game/map/api/region-versions

http-метод:

GET

версии:

0.1

параметры:

нет

ошибки:

нет

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

{
    "turns": [<целое>, ...] // номер хода, для которого есть карта
}

PvP: Отправить героя на арену

Отправить заявку на бой на арене.

адрес:

/game/pvp/api/call-to-arena

http-метод:

POST

версии:

0.1

параметры:

нет

ошибки:

нет

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

{
    "info": <pvp_info> // актуальная информация о pvp боях и вызовах
}

<pvp_info> = {"accounts": <accounts_info>,         // краткая дополнительная информация об игроках, относящихся к pvp
              "clans": <clans_info>                // краткая дополнительная информация о кланах, относящихся к pvp
              "active_arena_battles": <целое>,     // количество активных боёв между игроками
              "active_bot_battles": <целое>,       // количество активных боёв с ботами
              "arena_battle_requests": [<arena_battle_request>, ...]} // список активных вызовов на арену

<arena_battle_request> = {"id": <целое>,              // идентификатор вызова
                          "initiator_id": <целое>,    // идентификатор игрока, отправившего вызов
                          "matchmaker_type": <целое>, // тип боя, см. в списке типов
                          "created_at": <timestamp>,  // дата создания вызова
                          "updated_at": <timestamp>}  // дата обновления вызова

PvP: Отозвать героя с арены

Отозвать заявку на бой на арене.

адрес:

/game/pvp/api/leave-arena

http-метод:

POST

версии:

0.1

параметры:

нет

ошибки:

нет

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

{
    "info": <pvp_info> // актуальная информация о pvp боях и вызовах
}

PvP: Принять вызов другого игрока

Принять вызов другого игрока.

адрес:

/game/pvp/api/accept-arena-battle

http-метод:

POST

версии:

0.1

параметры:
  • GET: battle_request_id — идентификатор вызова

ошибки:
  • pvp.accept_arena_battle.no_battle_request_found — вызова не найден

  • pvp.accept_arena_battle.already_in_battle — вы или противник уже сражаетесь на арене

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

PvP: Начать бой с ботом

Начинает бой с ботом, если есть свбодные боты.

адрес:

/game/pvp/api/create-arena-bot-battle

http-метод:

POST

версии:

0.1

параметры:

нет

ошибки:
  • pvp.create_arena_bot_battle.no_free_bots — нет свободных ботов, надо повторить попытку позже

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

PvP: получить информацию о pvp боях и вызовах

Возвращает информацию о текущих вызовах и боях.

адрес:

/game/pvp/api/info

http-метод:

GET

версии:

0.1

параметры:

нет

ошибки:

нет

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

{
    "info": <pvp_info> // актуальная информация о pvp боях и вызовах
}