API для околоигровых ресурсов

Находится по адресу: http://haddan.ru/inner/api.php

Для начала хотелось бы попросить скриптеров клан-сайтов записывать полученную информацию себе на сайт статично, а не производить при каждом открытии вашей странички получение информации с API: это замедлит скорость загрузки вашего сайта и увеличит нагрузку на нашу базу данных. Прошу отнестись с пониманием.

Введен таймаут на одинаковые запросы 25 секунд! Т.е. 2 раза информацию об одном игроке можно запросить только раз в 25 секунд.

Теперь о самом простом способе получения информации (в виде небольшого мануальчика ).
1. При получении информации с АПИ лучше всего пользоваться соединением через socket, но если вы не умеете, то можно воспользоваться какой-нибудь простой функцией file_get_contents().
2. Для обработки XML вам будет достаточно SimpleXML (PHP5). В остальных случаях ваши проблемы решит эта библиотека: http://www.phppal.com/xml/doc.php.
(в случае, если у вас PHP4, и вы не хотите пользоваться простой библиотекой, то также есть возможности для обработки XML, почитайте http://www.php.net/manual/ru/function.xml-parse.php, а именно http://www.php.net/manual/ru/functio...arse.php#35708), т.о. после получения инфы пользуетесь simplexml_load_string(). Если вы не знаете структуру полученного функцией объекта, воспользуйтесь print_r.
Вот как раз пример:
[php]<?php
$file = file_get_contents("http://haddan.ru/inner/api.php?op=user&name=test13&fields=lastlogin,onlin e,roomname");
$xml = simplexml_load_string($file);
print_r($xml);
?>[/php]
Если у вас нет PHP5, то есть много других способов обработки XML.
Еще для тех, у кого нет PHP5 или нужно обработать BonReq's, которые SimpleXML не берет. Структура получается сложнее SimpleXML, однако полнее:
[php]<?php
function readXml($domnode, &$array)
{
$array_ptr = &$array;
$domnode = $domnode->firstChild;
while (!is_null($domnode))
{
switch ($domnode->nodeType)
{
case XML_TEXT_NODE: if(!(trim($domnode->nodeValue) == ""))
$array_ptr['cdata'] = $domnode->nodeValue;
break;
case XML_ELEMENT_NODE:
$array_ptr = &$array[$domnode->nodeName][];
if ($domnode->hasAttributes() )
{
$attributes = $domnode->attributes;
foreach ($attributes as $index => $domobj)
{
$array_ptr[$domobj->name] = $domobj->value;
}
}
break;
}
if ( $domnode->hasChildNodes() )
{
readXml($domnode, $array_ptr);
}
$domnode = $domnode->nextSibling;
}
}
$ar = array();
$api = @file_get_contents("http://haddan.ru/inner/api.php?op=thing&fields=all&ttid=1");
$d = new DOMDocument();
$d->LoadXML($api);
readXml($d, $ar);
print_r($ar);
?>[/php]
3. В случае ошибки будет возвращен текст ошибки в тэге <error />.

Подробнее о возможностях будет сказано ниже.

Тип получаемых данных передается по параметру "op".
Возможные варианты использования (будут пополняться).

1. Информация о персонаже (op=user).
Необходимо для получения различной конкретной информации об 1 персонаже.
Обязательный параметр id (ID получаемого персонажа) или name (имя персонажа).
Далее в параметре fields через запятую передаются поля, которые вы хотите получить. Доступные элементы параметра fields (аналогично будут называться тэги XML, все даты в формате unixtime):
userid (ID персонажа), username (Имя персонажа),registered (дата регистрации), lastlogin (последний заход в игру), race (раса в виде elf|human|orc... и т.п.), clan (ID клана),sex (пол в формате 0|1, где 0 - женский, 1 - мужской), wins (количество побед), loses (количество поражений), draws (количество ничей), battleid (ID боя персонажа, если 0 - не в бою), deaths (количество смертей), killedpc (убито PC), killednpc (убито NPC), hitpc (нанесено урона PC), hitnpc (нанесено урона NPC), slogan (Девиз), about (Поле "О себе"),level (уровень),clanname (название клана), online (В игре ли персонаж или нет, 0 - нет, 1 - да), roomname (Название комнаты, в которой находится персонаж), racename (Название расы в виде Человек|Орк и т.п.), realname (Реальное имя), city (Город), country (Страна), icq (ICQ), aligImage (изображение склонности, относительно относительно http://haddan.ru/images/align/, однако не советую вам пользоваться картинками с сервера Хаддана: на случай, если сервер будет недоступен) ,aligTitle (название склонности), родные статы персонажа: str (сила персонажа),dex (ловкость), inu (интуиция),rag (злость), con (выносливость),int (интеллект), wis (мудрость) и eng (энергетика), а также hpc (текущий уровень жизни персонажа),profession (профессия), prof_rank (уровень профессии численно, таблицу соответствия можно составить самому )
Пример запроса. Результатом http://localhost/inner/api.php?op=user&id=7231&fields=username,level,race ,racename будет:

 
<?xml version="1.0" encoding="utf-8" ?> 
- <haddan err="0" op="user">
  <username>Сайлас</username> 
 
  <level>25</level> 
 
  <race>human</race> 
 
  <racename>Человек</racename> 
 
</haddan>
 
 

UPDATE: Добавлена возможность просмотра одежды на персонаже.
Добавлена возможность опции wear в операции user (op=user). Выводит список одежды на персонаже на данный момент.
Пояснения по структуре:
<wear> - все понятно
<place id="XXX"> - тип вещи (здесь - это первое кольцо), для тех, кто знает английский проблем не возникнет, кто не знает - в словари :-)
<thingid>Integer</thingid> - ID вещи
<name>String</name> - название вещи
<image>http://haddan.ru/images/t/???</image> - абсолютная ссылка на вещь
<BonusReqs> - бонусы и требования
<Requirments> - требования
<Req name="XXX">Value</Req> - название требования со значением
...
</Requirments>
<Bonus> - бонусы
<Bon name="XXX">Value</Bon> - название бонуса со значением
...
</Bonus>
</BonusReqs>
<dur>Int</dur> - максимальный износ
<durc>Int</durc> - текущий износ
<weight>Int</weight> - Вес
<price>Int</price> - цена
<ro>Boolean</ro> - подходит или нет вещь
</place>
...
</wear>
Думаю, что там будет все достаточно понятно. Если будут вопросы задавайте.
UPDATE: добавлена возможность просмотра эффектов на персонаже.
Добавлена возможность опции effects в операции user (op=user). Выводит список эффектов на персонаже на данный момент.
Пояснения по структуре:
<effects> - все понятно
<effect id="XXX"> - тип эффекта
<name>String</name> - название эффекта
<inbattle>Boolean</inbattle> наложено ли в бою
<BonusReqs> - бонусы и требования
<Requirments> - требования
<Req name="XXX">Value</Req> - название требования со значением
...
</Requirments>
<Bonus> - бонусы
<Bon name="XXX">Value</Bon> - название бонуса со значением
...
</Bonus>
</BonusReqs>
<image>http://haddan.ru/images/x/???</image> - абсолютная ссылка на картинку эффекта
<till>Int</till> Время, которое еще будет держаться бонус(если inbattle не 0 то в количестве ходов, если не зависит от времени то равно 0)
<ro>Boolean</ro> - аналогично вещи: действует ли эффект (если <ro> определна, можно игнорировать)
</effect>
...
</effects>
2. Информация о пользователях в клане (op=clan).
Необходимо для получения информации о пользователях в конкретном клане.
Параметр для передачи: clanid (id клана) или clanname (название клана).
Возвращает список персонажей с определенными параметрами, значения которых по вышенаписанному, думаю, будут понятны.
Пример: http://haddan.ru/inner/api.php?op=clan&clanid=minister вернет:

 <?xml version="1.0" encoding="utf-8" ?> 
- <haddan err="0" op="clan">
- <user id="1">
  <userid>1</userid> 
 
  <username>dukei</username> 
 
  <clan>minister</clan> 
 
  <sex>1</sex> 
 
  <race>elf</race> 
 
  <level>25</level> 
 
  <clanname>Посланники Богов</clanname> 
 
  <icon /> 
 
  <online>0</online> 
 
  <align /> 
 
  </user>
 
 
- <user id="2799">
  <userid>2799</userid> 
 
  <username>Maelstorm</username> 
 
  <clan>minister</clan> 
 
  <sex>1</sex> 
 
  <race>human</race> 
 
  <level>17</level> 
 
  <clanname>Посланники Богов</clanname> 
 
  <icon /> 
 
  <online>0</online> 
 
  <align>Сила: Некромант, Душа: Хранитель Духа;chaoticevil.gif</align> 
 
  </user>
 
 
- <user id="3676">
  <userid>3676</userid> 
 
  <username>Warius</username> 
 
  <clan>minister</clan> 
 
  <sex>1</sex> 
 
  <race>human</race> 
 
  <level>22</level> 
 
  <clanname>Посланники Богов</clanname> 
 
  <icon /> 
 
  <online>0</online> 
 
  <align /> 
 
  </user>
 
 
- <user id="7231">
  <userid>7231</userid> 
 
  <username>Сайлас</username> 
 
  <clan>minister</clan> 
 
  <sex>1</sex> 
 
  <race>human</race> 
 
  <level>25</level> 
 
  <clanname>Посланники Богов</clanname> 
 
  <icon /> 
 
  <online>1</online> 
 
  <roomname>Банк, Главная площадь, Староград</roomname>
 
  <align>Сердце: Магистр Сердца, Душа: Магистр Души;chaoticgood.gif</align> 
 
  </user>
 
 
</haddan>
 
 

Единственное пояснения по тэгу <align />: там до ";" находится название склонности, а после - название картинки относительно http://haddan.ru/images/align/, однако не советую вам пользоваться картинками с сервера Хаддана: на случай, если сервер будет недоступен.

3. Информация о всех клана (op=allclans).
Выдает информацию о всех существующих кланах. Структура предельно понятна и не требует объяснений, я думаю.

4. Информация о вещи (op = thing)
Выдает достаточно полную информацию о запрашиваемой вещи.
Переменные запроса:
1. tid или ttid (thingID или thingtypeID - запрашивается конкретная вещь или целый тип)
2. fields: 'thingid'*, 'thingtypeid', 'name', 'image', 'imagebig', 'dur', 'durc'*, 'weight', 'price', 'br' (бонусы и требования),'typefull' (полный тип вещи, думаю человек, разбирающийся в английском хоть немного сразу поймет),'resInfo' (информация по производимым ресурсам в виде id => кол-во),'description','valid'(срок действия с момента изготовления), 'alchresInfo' (аналогично resInfo, но для алхимика)
И отдельно: 'all' - выводит все доступные поля
* - эти поля доступны только при запросе tid

5. Информация о ценах на ресурсы в государственных магазинах (op - governprice)
Выводит цены для ресурсов в государственных магазинах. Структура, думаю, понятна.



Не связанное напрямую с api.php:
1. Describer.php. Для создания анализатора логов боев наш Describer.php. В нем содержатся весь инстурментарий для описания лога боя у нас. Я думаю за полчасика можно его понять и на основе его создать анализатор лога.

Добавлена возможность опции wear в операции user (op=user). Выводит список одежды на персонаже на данный момент.
Пояснения по структуре:
<wear> - все понятно
<place id="XXX"> - тип вещи (здесь - это первое кольцо), для тех, кто знает английский проблем не возникнет, кто не знает - в словари :-)
<thingid>Integer</thingid> - ID вещи
<name>String</name> - название вещи
<image>http://haddan.ru/images/t/???</image> - абсолютная ссылка на вещь
<BonusReqs> - бонусы и требования
<Requirments> - требования
<Req name="XXX">Value</Req> - название требования со значением
...
</Requirments>
<Bonus> - бонусы
<Bon name="XXX">Value</Bon> - название бонуса со значением
...
</Bonus>
</BonusReqs>
<dur>Int</dur> - максимальный износ
<durc>Int</durc> - текущий износ
<weight>Int</weight> - Вес
<price>Int</price> - цена
<ro>Boolean</ro> - подходит или нет вещь
</ring1>
...
</wear>
Думаю, что там будет все достаточно понятно. Если будут вопросы задавайте.

Модификаторы, действующие только при воздействии с этой вещью выделены тэгами <i>.

Добавлена возможность опции effects в операции user (op=user). Выводит список эффектов на персонаже на данный момент.
Пояснения по структуре:
<effects> - все понятно
<effect id="XXX"> - тип эффекта
<name>String</name> - название эффекта
<inbattle>Boolean</inbattle> наложено ли в бою
<BonusReqs> - бонусы и требования
<Requirments> - требования
<Req name="XXX">Value</Req> - название требования со значением
...
</Requirments>
<Bonus> - бонусы
<Bon name="XXX">Value</Bon> - название бонуса со значением
...
</Bonus>
</BonusReqs>
<image>http://haddan.ru/images/x/???</image> - абсолютная ссылка на картинку эффекта
<till>Int</till> Время, которое еще будет держаться бонус(если inbattle не 0 то в количестве ходов, если не зависит от времени то равно 0)
<ro>Boolean</ro> - аналогично вещи: действует ли эффект (если <ro> определна, можно игнорировать)
</effect>
...
</effects>

3. Информация о всех клана (op=allclans).
Выдает информацию о всех существующих кланах. Структура предельно понятна и не требует объяснений, я думаю.

4. Информация о вещи (op = thing)
Выдает достаточно полную информацию о запрашиваемой вещи.
Переменные запроса:
1. tid или ttid (thingID или thingtypeID - запрашивается конкретная вещь или целый тип)
2. fields: 'thingid'*, 'thingtypeid', 'name', 'image', 'imagebig', 'dur', 'durc'*, 'weight', 'price', 'br' (бонусы и требования),'typefull' (полный тип вещи, думаю человек, разбирающийся в английском хоть немного сразу поймет),'resInfo' (информация по производимым ресурсам в виде id => кол-во),'description','valid'(срок действия с момента изготовления)
И отдельно: 'all' - выводит все доступные поля
* - эти поля доступны только при запросе tid

Еще для тех, у кого нет PHP5 или нужно обработать BonReq's, которые SimpleXML не берет. Структура получается сложнее SimpleXML, однако полнее:
[php]<?php
function readXml($domnode, &$array)
{
$array_ptr = &$array;
$domnode = $domnode->firstChild;
while (!is_null($domnode))
{
switch ($domnode->nodeType)
{
case XML_TEXT_NODE: if(!(trim($domnode->nodeValue) == ""))
$array_ptr['cdata'] = $domnode->nodeValue;
break;
case XML_ELEMENT_NODE:
$array_ptr = &$array[$domnode->nodeName][];
if ($domnode->hasAttributes() )
{
$attributes = $domnode->attributes;
foreach ($attributes as $index => $domobj)
{
$array_ptr[$domobj->name] = $domobj->value;
}
}
break;
}
if ( $domnode->hasChildNodes() )
{
readXml($domnode, $array_ptr);
}
$domnode = $domnode->nextSibling;
}
}
$ar = array();
$api = @file_get_contents("http://haddan.ru/inner/api.php?op=thing&fields=all&ttid=1");
$d = new DOMDocument();
$d->LoadXML($api);
readXml($d, $ar);
print_r($ar);
?>[/php]

Добавлены поля в op = userid и clan: profession (профессия), prof_rank (уровень профессии численно, таблицу соответствия можно составить самому )

Изменена работа roomname в op=user: теперь она выводит "Астрал", если персонаж оффлайн, если же в сети, то выводит полное его местонахождение.
Также добавлен параметр roomname в op=clan, просьба всем, кто использовал вместо с op=clan op=user для определения местонахождения (напр. Пегасам) переделать так, чтобы бралась инфа только из clan: это ускорит и вас и нас.

Введен таймаут на одинаковые запросы 10 секунд! Т.е. 2 раза информацию об одном игроке можно запросить только раз в 10 секунд.