Библиотека берет на себя всё общение с API игрового клиента (avatar.StartInspect, avatar.EndInspect, EVENT_INSPECT_STARTED, EVENT_INSPECT_FINISHED), скрывая от аддона особенности их работы, самостоятельно решая возможные конфликты между аддонами, и выдает в аддон результат инспектирования в удобном виде.

Прошу разработчиков принять участие в тестировании

Если кто-то увидит или наткнется на какой-либо баг, огромная просьба писать сюда.

Если есть предложения по работе аддона, фичам и содержанию таблицы, то тоже пишите сюда.

Библиотека позаимствовала многие идеи из аддона TPI и немного из LibreGS, так что их авторам look_at_you_ и vitaliy75 огромное спасибо за вклад.

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

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

Поддерживает функцию unit.GetGearScore, добавленную в хотфиксе 6.0.00.36.

На данный момент отсутствует подсчет гирскора для версий Аллодов 1.1-4.x. Если кто может, пожалуйста, поделитесь формулой или исходником.

Как пользоваться:

Опускаю подробности о добавлении скрипта в AddonDesc.(UIAddon).xdb...

Существует несколько вариантов использования библиотеки:

Если ваш аддон только для инспектировния текущей цели аватара, то необходимо выполнить следующие действия:

I. Инициализировать библиотеку любым из следующих способов:

Вызвать функцию GS.Init:
```
if GS.Init then GS.Init() end
```
Вызвать функцию GS.EnableTargetInspection:
```
GS.EnableTargetInspection( true )
```
Платным аддонам рекомендуется это делать после прохождения проверки системы привязки к нику персонажа.

II. Обеспечить прием данных любым из следующих способов:

Подписаться на сообщение LIBGS_GEARSCORE_AVAILABLE

common.RegisterEventHandler( ShowGearScore, "LIBGS_GEARSCORE_AVAILABLE" )

Установить функцию обратного вызова
```
GS.Callback = ShowGearScore
```

ShowGearScore - функция вашего аддона, которая будет отображать гирскор в нужное окно.

Имя функции может быть любое.

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

ShowGearScore должна быть уже объявлена на момент попытки её использования.

Например:

function ShowGearScore( params )
  if params.unitId == avatar.GetTarget() then
    if params.gearscore then
      MyWidget:SetClassVal("style", params.gearscoreStyle)
      MyWidget:SetVal("gs", tostring(params.gearscore))
      MyWidget:Show(true)
    else
      MyWidget:SetClassVal("style", "tip_white")
      MyWidget:SetVal("gs", "N/A")
      MyWidget:Show(true)
    end
  end
end

Аддону следует позаботиться о том, чтобы скрывать интерфейс в случае переключения таргета на НПС или сброса таргета, т.к. LibGS не присылает в этих случаях никаких сообщений.

function onTargetChaged(params)
  local unitId = avatar.GetTarget()
  if not unitId or not object.IsUnit( unitId ) or not unit.IsPlayer( unitId ) or unit.IsPet( unitId ) then
    MyWidget:Show(false)
  end
end

Если ваш аддон для инспектировния любых юнитов (без выделения юнита в таргет), то для получения гирскора вышеуказанным способом необходимо вызвать функцию GS.RequestInfo:

GS.RequestInfo ( unitIdToInspect )

И в ShowGearScore, соответственно, сделать:

if params.unitId == unitIdToInspect then ...

В данном случае инициализировать библиотеку не обязательно, но желательно, несмотря на то, что она может инициализировать себя сама.

На данный момент существует ~~проблема~~ особенность: если пользователь открыл встренное в клиент окно инспектирования, то инспектирование любого юнита не будет произведено, пока окно не будет закрыто.

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

Если ваш аддон не предназначен для инспектировния текущей цели аватара, то рекомендуется отключить функцию автоматического инспектирования:

GS.EnableTargetInspection( false )

Описание функций:

GS.Init ( EnableTargetAutoInspection, SkipInitialTargetInspection )

Инициализирует библиотеку.

Параметры функции аналогичны параметрам функции GS.EnableTargetInspection.

GS.EnableTargetInspection ( Enable, SkipInitial )

Включает/отключает автоматическое инспектирование при смене цели аватара.

Параметры:

1. Enable: boolean

true/nil - Включить авто-испектирование

false - Выключить авто-испектирование

2. SkipInitial: boolean

Имеет смысл только при Enable=true/nil.

По умолчанию, при перезагрузке аддона через меню дополнений LibGS автоматически проинспектирует текущую цель аватара.

SkipInitial позволяет пропустить инспектирование, например, если библиотека инциализируется не с начала работы аддона.

true - Пропустить инспектирование

false/nil - Инспектировать текущую цель

Следует помнить, что при перезагрузке всех аддонов, другие аддоны могут запрашивать инспектирование цели при инициализации, что приведет к приходу соообщения LIBGS_GEARSCORE_AVAILABLE раньше, чем может ожидаться.

Функция аддона, получающая результат инспектирования (ShowGearScore) должна учитывать это.

GS.RequestInfo ( unitId )

Запрашивает инспектирование юнита

Параметры:

unitId: ObjectId

Id юнита, которого надо происпектировать.

LIBGS_GEARSCORE_AVAILABLE ( params )

Глобальное сообщение с результатами инспектирования, посылаемое из ведущей LibGS после завершения инспектирования.

Следует помнить, что если аддон подписывается на сообщение LIBGS_GEARSCORE_AVAILABLE, то сообщение может приходить даже если аддон не запрашивал инспектирование какого-либо юнита.

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

Функция аддона, получающая результат инспектирования (ShowGearScore) должна учитывать это.

GS.Callback ( params )

Функция аддона, которая будет вызвана из локального экземпляра LibGS при получении сообщения LIBGS_GEARSCORE_AVAILABLE.

Аддон устанавливает это поле при необходимости, если не желает получать результат инспектирования через сообщение LIBGS_GEARSCORE_AVAILABLE.

В качестве параметра в обработчик LIBGS_GEARSCORE_AVAILABLE (и в GS.Callback, если задана) передается таблица со следующими полями:

unitId                  - ObjectId - Id юнита для которого подсчитан гирскор
rank                    - number - ранг умения аватара Пристальный взгляд (0..6)
inspected               - boolean - можно ли происпектировать юнит частично или полностью (ранг достаточно высок) (false, true)
reliable                - boolean - полностью ли происпектирован юнит (ранг достаточно высок) (false, true)

Поля gearscore* могут отсутствовать, если у аватара недостаточный ранг умения (inspected==false).
gearscore               - number - гирскор юнита
gearscoreLevel          - number - средний уровень экипировки юнита, кроме драконьего облика (1..66)
gearscoreQuality        - number - "актуальность" экипировки юнита - среднее качество, скорректированное с учетом разницы уровня игрока и экипировки, кроме драконьего облика (1..8 соответствует значениям между ITEM_QUALITY_JUNK..ITEM_QUALITY_RELIC)
gearscoreStyle          - string - рекомендуемый стиль для отображения значения гирскора ('Junk'..'Relic')

Поля equipment* могут отсутствовать, если у аватара недостаточный ранг умения (inspected==false).
equipmentLevel          - number - средний уровень экипировки юнита, кроме драконьего облика (1..66)
equipmentQuality        - number - среднее качество экипировки юнита, кроме драконьего облика (1..8 соответствует значениям между ITEM_QUALITY_JUNK..ITEM_QUALITY_RELIC)
equipmentStyle          - string - рекомендуемый стиль для отображения среднего качества экипировки ('Junk'..'Relic')

Поля runes* могут отсутствовать, если у аватара недостаточный ранг умения (inspected==false), или находимся на Pay-To-Play сервере.
runes                   - таблица, индексированная по [DRESS_SLOT_*RUNE*], элемент - таблица с полями:
    runeScore           - number - бонус к урону или лечению, даруемый данной руной в данный момент, в зависимости от того, куда она вставлена (0..??
    runeQuality         - number - ступень руны (0..13)
    runeStyle           - string - рекомендуемый стиль для отображения ступени ('Junk', 'Common'..'Legendary')
runesQuality            - number - средняя ступень всех рун (0..13)
runesQualityOffensive   - number - средняя ступень всех рун в атакующих слотах (0..13)
runesQualityDefensive   - number - средняя ступень всех рун в защитных слотах (0..13)
runesScoreOffensive     - number - общий бонус всех рун в атакующих слотах (0..??
runesScoreDefensive     - number - общий бонус всех рун в защитных слотах (0..??
runesStyle              - string - рекомендуемый стиль для отображения runesQuality ('Junk', 'Common'..'Legendary')
runesStyleOffensive     - string - рекомендуемый стиль для отображения runesQualityOffensive ('Junk', 'Common'..'Legendary')
runesStyleDefensive     - string - рекомендуемый стиль для отображения runesQualityDefensive ('Junk', 'Common'..'Legendary')

Некоторые поля fairy* могут отсутствовать в зависимости от версии игрового клиента.
fairy                   - string - ступень покровителя для отображения ('-', 'I'..'V')
fairyLevel              - number - уровень покровителя (1..65)
fairyQuality            - number - ступень покровителя (0..5)
fairyScore              - number - [AO 3-4] бонус характиристики, даруемый покровителем (0..???)
fairyScoreStat          - number - [AO 3-4] тип характиристики (INNATE_STAT_*)
fairyScorePower         - number - [AO 5-6] бонус могущества (0..???)
fairyScoreDamage        - number - бонус к урону (0..250%)
fairyScoreHeal          - number - бонус к лечению (0..250%)
fairyStyle              - string - рекомендуемый стиль для отображения ступени покровителя ('Junk', 'Goods'..'Epic')

Поля *Style можно напрямую передавать в функцию MyTextView:SetClassVal().

Пример аддона LibreGS, переделанного под использование LibGS. Можно также обратить внимание на onTargetChaged, скрывающий интерфейс аддона:

--------------------------------------------------------------------------------
-- GLOBALS
--------------------------------------------------------------------------------

local ouText=nil
local vtHello=nil

--------------------------------------------------------------------------------
-- EVENT HANDLERS
--------------------------------------------------------------------------------

function onSize(params)
 local pco=widgetsSystem:GetPosConverterParams()
 local plc=mainForm:GetPlacementPlain()
 plc.alignY=WIDGET_ALIGN_LOW
 plc.highPosY=0
 plc.posY=0
 plc.sizeY=157
 plc.alignX=WIDGET_ALIGN_LOW
 plc.posX=380
 plc.sizeX=400
 mainForm:SetPlacementPlain(plc)
end

function onTargetChaged(params)
 local tid=avatar.GetTarget()
 if not tid or not unit.IsPlayer(tid) then
  mainForm:Show(false)
 end
end

function ShowGearScore(params)
  if params.unitId == avatar.GetTarget() then
    ouText:SetVal("ttt",userMods.ToWString(tostring(math.floor(params.gearscore+0.5))))
    mainForm:Show(true)
  end
end

--------------------------------------------------------------------------------
-- INITIALIZATION
--------------------------------------------------------------------------------
function Init()
 if GS.Init then GS.Init() end
 onSize(nil)
 mainForm:SetPriority(7000)
 mainForm:SetTransparentInput(true)
 mainForm:Show(true)

 ouText=mainForm:GetChildChecked("ouText",false)
 vtHello=common.CreateValuedText()
 vtHello:SetFormat(userMods.ToWString([[<html><log fontsize="20"><r name="ttt"/></log></html>]]))
 ouText:SetValuedText(vtHello)
 ouText:Show(true)
 local plc=ouText:GetPlacementPlain()
 plc.posX=0
 plc.posY=0
 ouText:SetPlacementPlain(plc)
 
 ouText:SetBackgroundColor( { r = 0.1; g = 0.1; b = 0.05; a = 0.9 } )
 
 common.RegisterEventHandler( onTargetChaged, "EVENT_AVATAR_TARGET_CHANGED")
 common.RegisterEventHandler( ShowGearScore, "LIBGS_GEARSCORE_AVAILABLE")
 common.RegisterEventHandler( onSize, "EVENT_POS_CONVERTER_CHANGED")
 
end
--------------------------------------------------------------------------------
Init()
--------------------------------------------------------------------------------