WowAce

AbsorbsMonitor is depedendant on LibStub, CallbackHandler, AceTimer, AceComm and AceSerializer. If you want to embed AbsorbsMonitor, make sure to include these libraries and have them loaded before AbsorbsMonitor itself.

The main use of AbsorbsMonitor is through the events the library generates by watching the combat log. It uses CallbackHandler for this purpose, so you can use the known API to register any callbacks for it:

local AbsorbsMonitor = LibStub("AbsorbsMonitor-1.0");

function MyAddon:OnEnable()
    AbsorbsMonitor.RegisterCallback(self, "EffectApplied");
end

function MyAddon:OnDisable()
    AbsorbsMonitor.UnregisterAllCallbacks(self);
end

function MyAddon:EffectApplied(...)
end

Events

Common arguments:

sourceGUID, sourceName, destGUID, destName, spellId, value

GUID and name for the unit that caused the absorb effect (source) or got afflicted by it (dest) as well as the spell involved and absorb amount (value)

quality

A number between 0.0 and 1.0 indicated how accurate the given absorb value is. 1.0 means exact while 0.0 means wrong for sure. The quality for a unit or effect can only go down, never up. If all effects on any given unit had a quality of 1.0, and it is afflicted by an effect with 0.5, the resulting quality is 0.5. It can only reset if all absorb effects faded.

The following events are always fired, independent of the effects present on the target.

EffectApplied

sourceGUID, sourceName, destGUID, destName, spellId, value, quality, duration

Caused whenever an absorb effect is applied on a unit (not when it gets refreshed!). The amount can be zero, if the absorb amount could not be guessed or calculated. It will be (exactly!) -1 if the absorb amount is infinite (e.g. Astral Shift) OR if it is governed by something else like on area effects (e.g. Anti-Magic Zone). The duration can be nil if it is infinite or arbitrary (Astral Shift again).

EffectUpdated

guid, spellId, value, [duration]

Caused whenever an active absorb effect is updated in terms of value or duration. The duration will be non-nil only if it got refreshed and nil in all other cases. The value can be less than zero for infinite effects. It can also be higher than the previous value or the previous maximum if the effect got overwritten by a stronger version of itself (e.g. Divine Aegis).

EffectRemoved

guid, spellId

Caused whenever an active absorb effect is removed. This event is not fired it got refreshed, but only it is faded once completely.

AreaCreated

sourceGUID, sourceName, triggerGUID, spellId, value, quality

Caused when an area absorb effect was casted by the source unit. Area effects are implemented in World of Warcraft by summoning an invisible unit (triggerGUID) that radiates the absorb effect. Note that for each unit afflicted by the area effect, you will get a separate EffectApplied event with the same spellId, the triggerGUID as source and an amount of -1

AreaUpdated

triggerGUID, value

Caused when an area absorb effect got hit by damage. Note that this event is much simpler than EffectUpdated, since area effects cannot overlap or get refreshed. There is also always one effect per trigger. You will not get separate EffectUpdated events for all units afflicted for performance reasons.

AreaCleared

triggerGUID

Caused when the created area effect and its trigger disappear

The following events are only fired for so called visible effects. These effects include general purpose absorb spells like Power Word: Shield, Divine Aegis, Sacrifice and others, but not special purpose effects like Anti-Magic Shell, Shadow Ward or Savage Defense. While those effects are used in the calculation, they do count against the same "total" absorb value.

UnitUpdated

guid, value, quality

Caused when the total absorb value for a unit changed. This can get fired when it is afflicted by an absorb effect, hit for damage or it's removed.

UnitCleared

Caused when a unit previously afflicted by absorb effects is now completely clear. This means that the quality got also reset to 1.0. Note that this event obeys non-visible effects, but that will not make much of a difference in most cases.

Functions

These functions are not methods to be used with the colon operator, but only table entries:

local ap, sp = AbsorbsMonitor.Unit_Stats(guid);

RegisterEffectCallbacks

self, funcApplied, [ funcUpdated, [ funcRemoved ] ]

Shortcut to registering the three Effect callbacks. If funcUpdated and/or funcRemoved are not specified or nil, funcUpdated is used.

RegisterAreaCallbacks

self, funcCreated, [ funcUpdated, [ funcCleared ] ]

see RegisterEffectCallbacks.

RegisterUnitCallbacks

self, funcUpdated, [ funcCleared ]

see RegisterEffectCallbacks

GetLowVauleTolerance/SetLowValueTolerance

Gets/Sets the low value tolerance. This parameter decides how much an absorb effect may be undervalued before the unit is marked with a quality of 0.0.

Test

Causes 6 virtual absorb effects on 3 virtual units to be created and appropriate events fired.

Unit_Effect

guid, spellId

Returns the absorb value of the given spell on the given unit or 0 if not present (will be changed to nil in a future version)

Unit_Total

Returns the total absorb value of the given unit. This only includes visible effects by the definition above.

Unit_EffectsList, Unit_EffectsMap

Returns a numerical table or a map indexed by spellId for a given unit. For performance reasons, this function returns the internal data structures used to store absorb effects, DO NOT MODIFY THEM!

ap, sp, mastery, quality = Unit_Stats

Returns the attack power, spell power and mastery (not rating!) of the given unit if known or 0, 0, 8, nil if not present. These rather odd return values on missing data are for internal performance reasons while calculating absorb data.

Unit_Scaling

Returns a table with scaling factors for the given unit. The table format is custom for each class. For performance reasons, this function returns the internal data structures used to store scaling data, DO NOT MODIFY THEM!